fix: handle required Epic Name fields during creation (sooperset#568)

* fix: handle required Epic Name fields during creation

- Check field requirements before deciding placement
- Include required Epic fields in initial creation request
- Keep optional Epic fields for post-creation update
- Add project_key parameter to enable requirement lookup

Github-Issue: sooperset#457

* fix: update test_create_epic mock to match new method signature

The prepare_epic_fields method now accepts 5 parameters including project_key,
so the test mock's side_effect function needs to be updated accordingly.

Reported-by:Hyeonsoo Lee
Github-Issue:sooperset#568

* perf: implement caching for get_required_fields to improve Epic creation performance

- Add caching mechanism in FieldsMixin.get_required_fields to avoid repeated API calls
- Remove unnecessary hasattr check in EpicsMixin since get_required_fields is guaranteed
- Add get_required_fields to FieldsOperationsProto for proper type checking
- Performance improvement critical for bulk Epic creation operations

The caching uses a tuple of (project_key, issue_type) as the cache key to store
required field definitions per project/issue type combination. This prevents
redundant API calls when creating multiple Epics in the same project.

Github-Issue: sooperset#568

* refactor: simplify Jira protocol tests by removing redundant classes and methods

- Removed multiple test classes and methods related to protocol definitions and method signatures for Jira operations.
- Consolidated tests to focus on protocol compliance checking.
- This cleanup reduces code complexity and improves maintainability of the test suite.

No functional changes were made to the protocol implementations themselves.

* revert: uv.lock

Author: sooperset

src/mcp_atlassian/jira/epics.py

@@ -111,7 +111,11 @@ def _try_discover_fields_from_existing_epic(
             logger.error(f"Error discovering fields from existing Epic: {str(e)}")
 
     def prepare_epic_fields(
-        self, fields: dict[str, Any], summary: str, kwargs: dict[str, Any]
+        self,
+        fields: dict[str, Any],
+        summary: str,
+        kwargs: dict[str, Any],
+        project_key: str = None,
     ) -> None:
         """
         Prepare epic-specific fields for issue creation.
@@ -120,33 +124,48 @@ def prepare_epic_fields(
             fields: The fields dictionary to update
             summary: The issue summary that can be used as a default epic name
             kwargs: Additional fields from the user
+            project_key: Optional project key for checking field requirements
         """
         try:
             # Get all field IDs
             field_ids = self.get_field_ids_to_epic()
             logger.info(f"Discovered Jira field IDs for Epic creation: {field_ids}")
 
-            # Store Epic-specific fields in kwargs for later update
-            # This is critical because the Jira API might reject these fields during creation
-            # due to screen configuration restrictions
+            # Get required fields for Epic issue type if project_key provided
+            required_fields = {}
+            if project_key:
+                try:
+                    required_fields = self.get_required_fields("Epic", project_key)
+                    logger.debug(
+                        f"Required fields for Epic in project {project_key}: {list(required_fields.keys())}"
+                    )
+                except Exception as e:
+                    logger.warning(f"Could not check field requirements: {e}")
 
-            # Extract and store epic_name for later update
+            # Extract and handle epic_name
             epic_name_field = self._get_epic_name_field_id(field_ids)
             if epic_name_field:
-                # Get epic name value but don't add to fields yet
+                # Get epic name value
                 epic_name = kwargs.pop(
                     "epic_name", kwargs.pop("epicName", summary)
                 )  # Use summary as default if epic_name not provided
 
-                # Instead of adding to fields, store in kwargs under a special key
-                # This will be used for the post-creation update
-                kwargs["__epic_name_field"] = epic_name_field
-                kwargs["__epic_name_value"] = epic_name
-                logger.info(
-                    f"Storing Epic Name ({epic_name_field}: {epic_name}) for post-creation update"
-                )
+                # Check if this field is required
+                if epic_name_field in required_fields:
+                    # Add to fields for initial creation
+                    fields[epic_name_field] = epic_name
+                    logger.info(
+                        f"Adding required Epic Name ({epic_name_field}: {epic_name}) to creation fields"
+                    )
+                else:
+                    # Store for post-creation update as before
+                    kwargs["__epic_name_field"] = epic_name_field
+                    kwargs["__epic_name_value"] = epic_name
+                    logger.info(
+                        f"Storing optional Epic Name ({epic_name_field}: {epic_name}) for post-creation update"
+                    )
 
-            # Extract and store epic_color for later update
+            # Extract and handle epic_color
             epic_color_field = self._get_epic_color_field_id(field_ids)
             if epic_color_field:
                 epic_color = (
@@ -156,23 +175,41 @@ def prepare_epic_fields(
                     or "green"  # Default color
                 )
 
-                # Store for post-creation update
-                kwargs["__epic_color_field"] = epic_color_field
-                kwargs["__epic_color_value"] = epic_color
-                logger.info(
-                    f"Storing Epic Color ({epic_color_field}: {epic_color}) for post-creation update"
-                )
+                # Check if this field is required
+                if epic_color_field in required_fields:
+                    # Add to fields for initial creation
+                    fields[epic_color_field] = epic_color
+                    logger.info(
+                        f"Adding required Epic Color ({epic_color_field}: {epic_color}) to creation fields"
+                    )
+                else:
+                    # Store for post-creation update
+                    kwargs["__epic_color_field"] = epic_color_field
+                    kwargs["__epic_color_value"] = epic_color
+                    logger.info(
+                        f"Storing optional Epic Color ({epic_color_field}: {epic_color}) for post-creation update"
+                    )
 
-            # Store any other epic-related fields for later update
+            # Handle any other epic-related fields
             for key, value in list(kwargs.items()):
                 if key.startswith("epic_") and key in field_ids:
                     field_key = key.replace("epic_", "")
-                    # Store for post-creation update
-                    kwargs[f"__epic_{field_key}_field"] = field_ids[key]
-                    kwargs[f"__epic_{field_key}_value"] = value
-                    logger.info(
-                        f"Storing Epic field ({field_ids[key]} from {key}: {value}) for post-creation update"
-                    )
+                    field_id = field_ids[key]
+
+                    # Check if this field is required
+                    if field_id in required_fields:
+                        # Add to fields for initial creation
+                        fields[field_id] = value
+                        logger.info(
+                            f"Adding required Epic field ({field_id} from {key}: {value}) to creation fields"
+                        )
+                    else:
+                        # Store for post-creation update
+                        kwargs[f"__epic_{field_key}_field"] = field_id
+                        kwargs[f"__epic_{field_key}_value"] = value
+                        logger.info(
+                            f"Storing optional Epic field ({field_id} from {key}: {value}) for post-creation update"
+                        )
                     kwargs.pop(key)  # Remove from kwargs to avoid duplicate processing
 
             # Warn if epic_name field is required but wasn't discovered

src/mcp_atlassian/jira/fields.py

@@ -188,6 +188,18 @@ def get_required_fields(self, issue_type: str, project_key: str) -> dict[str, An
         Returns:
             Dictionary mapping required field names to their definitions
         """
+        # Initialize cache if it doesn't exist
+        if not hasattr(self, "_required_fields_cache"):
+            self._required_fields_cache = {}
+
+        # Check cache first
+        cache_key = (project_key, issue_type)
+        if cache_key in self._required_fields_cache:
+            logger.debug(
+                f"Returning cached required fields for {issue_type} in {project_key}"
+            )
+            return self._required_fields_cache[cache_key]
+
         try:
             # Step 1: Get the ID for the given issue type name within the project
             if not hasattr(self, "get_project_issue_types"):
@@ -236,6 +248,13 @@ def get_required_fields(self, issue_type: str, project_key: str) -> dict[str, An
                     f"in project '{project_key}'"
                 )
 
+            # Cache the result before returning
+            self._required_fields_cache[cache_key] = required_fields
+            logger.debug(
+                f"Cached required fields for {issue_type} in {project_key}: "
+                f"{len(required_fields)} fields"
+            )
+
             return required_fields
 
         except Exception as e:

src/mcp_atlassian/jira/issues.py

@@ -732,11 +732,19 @@ def _prepare_epic_fields(
             summary: The epic summary
             kwargs: Additional fields from the user
         """
-        # Delegate to EpicsMixin.prepare_epic_fields
+        # Extract project_key from fields if available
+        project_key = None
+        if "project" in fields:
+            if isinstance(fields["project"], dict):
+                project_key = fields["project"].get("key")
+            elif isinstance(fields["project"], str):
+                project_key = fields["project"]
+
+        # Delegate to EpicsMixin.prepare_epic_fields with project_key
         # Since JiraFetcher inherits from both IssuesMixin and EpicsMixin,
         # this will correctly use the prepare_epic_fields method from EpicsMixin
         # which implements the two-step Epic creation approach
-        self.prepare_epic_fields(fields, summary, kwargs)
+        self.prepare_epic_fields(fields, summary, kwargs, project_key)
 
     def _prepare_parent_fields(
         self, fields: dict[str, Any], kwargs: dict[str, Any]

src/mcp_atlassian/jira/protocols.py

@@ -91,7 +91,11 @@ def update_epic_fields(self, issue_key: str, kwargs: dict[str, Any]) -> JiraIssu
 
     @abstractmethod
     def prepare_epic_fields(
-        self, fields: dict[str, Any], summary: str, kwargs: dict[str, Any]
+        self,
+        fields: dict[str, Any],
+        summary: str,
+        kwargs: dict[str, Any],
+        project_key: str = None,
     ) -> None:
         """
         Prepare epic-specific fields for issue creation.
@@ -153,6 +157,19 @@ def get_field_ids_to_epic(self) -> dict[str, str]:
             (e.g., {'epic_link': 'customfield_10014', 'epic_name': 'customfield_10011'})
         """
 
+    @abstractmethod
+    def get_required_fields(self, issue_type: str, project_key: str) -> dict[str, Any]:
+        """
+        Get required fields for creating an issue of a specific type in a project.
+
+        Args:
+            issue_type: The issue type (e.g., 'Bug', 'Story', 'Epic')
+            project_key: The project key (e.g., 'PROJ')
+
+        Returns:
+            Dictionary mapping required field names to their definitions
+        """
+
 
 @runtime_checkable
 class ProjectsOperationsProto(Protocol):