QA-MCP: Test Standardization & Orchestration Server

Instructions

Implementation Reference

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

  The primary handler function that performs the conversion from QA-MCP testcase format to Xray import JSON, handling field mappings, steps, custom fields, priority, labels, and generating reports/warnings.

  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,
      }

• src/qa_mcp/server.py:184-214 (registration)

  MCP tool registration defining the 'testcase.to_xray' tool name, description, and input schema.

  Tool(
      name="testcase.to_xray",
      description="Standart test case'i Xray import formatına dönüştürür",
      inputSchema={
          "type": "object",
          "properties": {
              "testcase": {
                  "type": "object",
                  "description": "Dönüştürülecek test case",
              },
              "project_key": {
                  "type": "string",
                  "description": "Jira proje anahtarı (örn: PROJ)",
              },
              "test_type": {
                  "type": "string",
                  "enum": ["Manual", "Automated", "Generic"],
                  "description": "Xray test tipi (default: Manual)",
              },
              "include_custom_fields": {
                  "type": "boolean",
                  "description": "Custom field'ları dahil et (default: true)",
              },
              "custom_field_mappings": {
                  "type": "object",
                  "description": "Custom field ID eşlemeleri",
              },
          },
          "required": ["testcase", "project_key"],
      },
  ),

• src/qa_mcp/server.py:354-362 (handler)

  Server-side tool dispatch handler that extracts arguments and invokes the convert_to_xray implementation.

  elif name == "testcase.to_xray":
      result = convert_to_xray(
          testcase=arguments["testcase"],
          project_key=arguments["project_key"],
          test_type=arguments.get("test_type", "Manual"),
          include_custom_fields=arguments.get("include_custom_fields", True),
          custom_field_mappings=arguments.get("custom_field_mappings"),
      )
      audit_log(name, arguments, f"Converted to Xray for {arguments['project_key']}")

• src/qa_mcp/tools/to_xray.py:12-31 (helper)

  Constant mappings for priority and test type conversion between QA-MCP and Xray formats.

  XRAY_PRIORITY_MAP = {
      Priority.P0: "Highest",
      Priority.P1: "High",
      Priority.P2: "Medium",
      Priority.P3: "Low",
  }
  
  XRAY_TEST_TYPE_MAP = {
      "Manual": "Manual",
      "Automated": "Generic",
      "Generic": "Generic",
  }
  
  
  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,