QA-MCP: Test Standardization & Orchestration Server

Instructions

Implementation Reference

• src/qa_mcp/tools/to_xray.py:142-203 (handler)

  The primary handler function for the 'testcase.to_xray_batch' tool. Converts a list of test cases to Xray format by processing each with convert_to_xray and aggregating results into bulk import payload.

  def convert_batch_to_xray(
      testcases: list[dict],
      project_key: str,
      test_type: str = "Manual",
      include_custom_fields: bool = True,
      custom_field_mappings: dict[str, str] | None = None,
  ) -> dict:
      """
      Convert multiple test cases to Xray import format.
  
      Args:
          testcases: List of test cases in QA-MCP standard format
          project_key: Jira project key
          test_type: Xray test type
          include_custom_fields: Whether to include custom fields
          custom_field_mappings: Custom field ID mappings
  
      Returns:
          Dictionary containing:
          - xray_payloads: List of Xray-ready payloads
          - import_payload: Combined payload for bulk import
          - summary: Conversion summary
          - warnings: Aggregated warnings
      """
      results = []
      all_warnings = []
      successful = 0
      failed = 0
  
      for idx, tc in enumerate(testcases):
          result = convert_to_xray(
              testcase=tc,
              project_key=project_key,
              test_type=test_type,
              include_custom_fields=include_custom_fields,
              custom_field_mappings=custom_field_mappings,
          )
  
          if result.get("error"):
              failed += 1
              all_warnings.append(f"Test case {idx + 1}: {result['error']}")
          else:
              successful += 1
              results.append(result["xray_payload"])
  
          all_warnings.extend(result.get("warnings", []))
  
      # Build bulk import payload (Xray JSON format)
      import_payload = {
          "tests": results,
      }
  
      return {
          "xray_payloads": results,
          "import_payload": import_payload,
          "summary": {
              "total": len(testcases),
              "successful": successful,
              "failed": failed,
          },
          "warnings": all_warnings,
      }

• src/qa_mcp/server.py:215-237 (registration)

  Registers the MCP tool 'testcase.to_xray_batch' with its input schema and description in the server's list_tools handler.

  Tool(
      name="testcase.to_xray_batch",
      description="Birden fazla test case'i toplu olarak Xray formatına dönüştürür",
      inputSchema={
          "type": "object",
          "properties": {
              "testcases": {
                  "type": "array",
                  "items": {"type": "object"},
                  "description": "Dönüştürülecek test case listesi",
              },
              "project_key": {
                  "type": "string",
                  "description": "Jira proje anahtarı",
              },
              "test_type": {
                  "type": "string",
                  "enum": ["Manual", "Automated", "Generic"],
              },
          },
          "required": ["testcases", "project_key"],
      },
  ),

• src/qa_mcp/server.py:364-374 (handler)

  MCP server call_tool dispatch branch that invokes the convert_batch_to_xray function with parsed arguments and handles audit logging.

  elif name == "testcase.to_xray_batch":
      result = convert_batch_to_xray(
          testcases=arguments["testcases"],
          project_key=arguments["project_key"],
          test_type=arguments.get("test_type", "Manual"),
      )
      audit_log(
          name,
          arguments,
          f"Batch converted {result.get('summary', {}).get('successful', 0)} to Xray",
      )

• src/qa_mcp/tools/to_xray.py:26-139 (helper)

  Core helper function for converting a single test case to Xray format, used by the batch handler. Builds the detailed Xray payload including field mappings, steps, and custom fields.

  def convert_to_xray(
      testcase: dict,
      project_key: str,
      test_type: str = "Manual",
      include_custom_fields: bool = True,
      custom_field_mappings: dict[str, str] | None = None,
  ) -> dict:
      """
      Convert a QA-MCP test case to Xray import format.
  
      Args:
          testcase: Test case in QA-MCP standard format
          project_key: Jira project key (e.g., 'PROJ')
          test_type: Xray test type - 'Manual', 'Automated', 'Generic'
          include_custom_fields: Whether to include custom field mappings
          custom_field_mappings: Custom field ID mappings (e.g., {'risk_level': 'customfield_10001'})
  
      Returns:
          Dictionary containing:
          - xray_payload: Ready-to-import Xray JSON
          - field_mapping_report: Which fields were mapped
          - warnings: Any conversion warnings
      """
      warnings = []
      field_mapping_report = {
          "mapped_fields": [],
          "unmapped_fields": [],
          "custom_fields_used": [],
      }
  
      # Parse test case
      try:
          tc = TestCase(**testcase)
      except Exception as e:
          return {
              "xray_payload": None,
              "field_mapping_report": field_mapping_report,
              "warnings": [f"Test case parse hatası: {str(e)}"],
              "error": str(e),
          }
  
      # Build Xray payload
      xray_payload = {
          "testtype": XRAY_TEST_TYPE_MAP.get(test_type, "Manual"),
          "fields": {
              "project": {"key": project_key},
              "summary": tc.title,
              "description": _build_xray_description(tc),
              "issuetype": {"name": "Test"},
          },
      }
      field_mapping_report["mapped_fields"].extend(["title", "description"])
  
      # Priority mapping
      if tc.priority:
          xray_payload["fields"]["priority"] = {"name": XRAY_PRIORITY_MAP.get(tc.priority, "Medium")}
          field_mapping_report["mapped_fields"].append("priority")
  
      # Labels
      labels = list(tc.labels) + list(tc.tags)
      if labels:
          xray_payload["fields"]["labels"] = labels
          field_mapping_report["mapped_fields"].append("labels")
  
      # Components (from module)
      if tc.module:
          xray_payload["fields"]["components"] = [{"name": tc.module}]
          field_mapping_report["mapped_fields"].append("module->components")
  
      # Test steps (Xray specific format)
      xray_steps = _build_xray_steps(tc)
      if xray_steps:
          xray_payload["steps"] = xray_steps
          field_mapping_report["mapped_fields"].append("steps")
  
      # Preconditions
      if tc.preconditions:
          xray_payload["preconditions"] = "\n".join(f"• {p}" for p in tc.preconditions)
          field_mapping_report["mapped_fields"].append("preconditions")
  
      # Custom fields
      if include_custom_fields:
          custom_fields = _build_custom_fields(tc, custom_field_mappings)
          if custom_fields:
              xray_payload["fields"].update(custom_fields)
              field_mapping_report["custom_fields_used"] = list(custom_fields.keys())
  
      # Track unmapped fields
      all_tc_fields = set(TestCase.model_fields.keys())
      mapped_base_fields = {
          "title",
          "description",
          "priority",
          "labels",
          "tags",
          "module",
          "steps",
          "preconditions",
      }
      unmapped = all_tc_fields - mapped_base_fields - {"id", "created_at", "updated_at", "author"}
  
      for field in unmapped:
          value = getattr(tc, field, None)
          if value and (not isinstance(value, list) or value):
              field_mapping_report["unmapped_fields"].append(field)
              warnings.append(
                  f"'{field}' alanı Xray'e map edilemedi - custom field ekleyin veya description'a dahil edildi"
              )
  
      return {
          "xray_payload": xray_payload,
          "field_mapping_report": field_mapping_report,
          "warnings": warnings,
      }