feat(jira): add custom field options MCP tools

Add three new MCP tools for retrieving Jira custom field options:
- jira_get_customfield_options: Get global options for a custom field
- jira_get_customfield_contexts: Get contexts for a custom field
- jira_get_customfield_context_options: Get context-specific options

Features:
- Cross-platform support (Cloud and Server/DC with appropriate API versions)
- Comprehensive input validation and error handling
- Pagination support with configurable limits
- Detailed logging and debugging capabilities
- Full authentication method support (API tokens, PAT, OAuth)

Implementation:
- New Pydantic models for field options, contexts, and responses
- API client methods in FieldsMixin with Cloud/Server detection
- MCP tool implementations with comprehensive parameter documentation
- Unit tests covering models, validation, and API version selection
- Updated documentation with new tools in README

Technical fixes:
- Use from_api_response() methods in API client for proper response parsing
- Handle both Cloud ('values') and DC/Server ('options') API response formats
- Robust pagination handling with fallbacks for missing DC/Server fields
- Enhanced error resilience for malformed responses

This enables AI assistants to discover available custom field options
before creating/updating Jira issues, improving automation accuracy.

Author: pibylick

README.md

@@ -730,6 +730,9 @@ Here's a complete example of setting up multi-user authentication with streamabl
 - `jira_update_issue`: Update an existing issue
 - `jira_transition_issue`: Transition an issue to a new status
 - `jira_add_comment`: Add a comment to an issue
+- `jira_get_customfield_options`: Get available options for custom fields
+- `jira_get_customfield_contexts`: Get contexts for custom fields
+- `jira_get_customfield_context_options`: Get options for custom fields within specific contexts
 
 #### Confluence Tools
 
@@ -749,6 +752,9 @@ Here's a complete example of setting up multi-user authentication with streamabl
 |           | `jira_get_worklog`                  | `confluence_get_labels`        |
 |           | `jira_get_transitions`              | `confluence_search_user`       |
 |           | `jira_search_fields`                |                                |
+|           | `jira_get_customfield_options`      |                                |
+|           | `jira_get_customfield_contexts`     |                                |
+|           | `jira_get_customfield_context_options` |                             |
 |           | `jira_get_agile_boards`             |                                |
 |           | `jira_get_board_issues`             |                                |
 |           | `jira_get_sprints_from_board`       |                                |

src/mcp_atlassian/jira/fields.py

@@ -5,6 +5,11 @@
 
 from thefuzz import fuzz
 
+from mcp_atlassian.models.jira.field_option import (
+    JiraFieldContextsResponse,
+    JiraFieldOptionsResponse,
+    JiraFieldContextOptionsResponse,
+)
 from .client import JiraClient
 from .protocols import EpicOperationsProto, UsersOperationsProto
 
@@ -524,3 +529,213 @@ def similarity(keyword: str, field: dict) -> int:
         except Exception as e:
             logger.error(f"Error searching fields: {str(e)}")
             return []
+
+    def get_field_contexts(
+        self,
+        field_id: str,
+        start_at: int = 0,
+        max_results: int = 10000,
+    ) -> JiraFieldContextsResponse:
+        """
+        Get contexts for a custom field.
+
+        Args:
+            field_id: The ID of the field (e.g., 'customfield_10001')
+            start_at: Starting index for pagination (default: 0)
+            max_results: Maximum number of results per page (default: 10000)
+
+        Returns:
+            JiraFieldContextsResponse with contexts for the field
+
+        Raises:
+            ValueError: If the field_id is not provided or invalid
+        """
+        if not field_id:
+            raise ValueError("Field ID is required")
+
+        if not field_id.startswith("customfield_"):
+            raise ValueError("Field ID must be a custom field (starting with 'customfield_')")
+
+        try:
+            logger.debug(f"Getting contexts for field '{field_id}'")
+            
+            # Use different API endpoints for Cloud vs DC/Server
+            if self.config.is_cloud:
+                # Cloud API
+                path = f"/rest/api/3/field/{field_id}/context"
+            else:
+                # DC/Server API - contexts endpoint may not exist or be different
+                # For DC, we'll use the same endpoint as Cloud but with API v2
+                path = f"/rest/api/2/field/{field_id}/context"
+            
+            params = {
+                "startAt": start_at,
+                "maxResults": max_results,
+            }
+
+            result = self.jira.get(
+                path=path,
+                params=params,
+            )
+
+            if not isinstance(result, dict):
+                error_msg = f"Unexpected response type from field contexts API: {type(result)}"
+                logger.error(error_msg)
+                raise ValueError(error_msg)
+
+            # Parse the response using our model
+            contexts_response = JiraFieldContextsResponse.from_api_response(
+                result, 
+                max_results=max_results
+            )
+            logger.debug(
+                f"Retrieved {len(contexts_response.values)} contexts for field '{field_id}'"
+            )
+            return contexts_response
+
+        except Exception as e:
+            logger.error(f"Error getting contexts for field '{field_id}': {str(e)}")
+            raise
+
+    def get_field_options(
+        self,
+        field_id: str,
+        start_at: int = 0,
+        max_results: int = 10000,
+    ) -> JiraFieldOptionsResponse:
+        """
+        Get options for a custom field (global options).
+
+        Args:
+            field_id: The ID of the field (e.g., 'customfield_10001')
+            start_at: Starting index for pagination (default: 0)
+            max_results: Maximum number of results per page (default: 10000)
+
+        Returns:
+            JiraFieldOptionsResponse with options for the field
+
+        Raises:
+            ValueError: If the field_id is not provided or invalid
+        """
+        if not field_id:
+            raise ValueError("Field ID is required")
+
+        if not field_id.startswith("customfield_"):
+            raise ValueError("Field ID must be a custom field (starting with 'customfield_')")
+
+        try:
+            logger.debug(f"Getting global options for field '{field_id}'")
+            
+            # Use different API endpoints for Cloud vs DC/Server
+            if self.config.is_cloud:
+                # Cloud API - different endpoint structure
+                path = f"/rest/api/3/field/{field_id}/option"
+            else:
+                # DC/Server API - uses customFields endpoint with numerical ID only
+                # Extract numerical ID from customfield_XXXXX
+                numerical_id = field_id.replace("customfield_", "")
+                path = f"/rest/api/2/customFields/{numerical_id}/options"
+            
+            params = {
+                "startAt": start_at,
+                "maxResults": max_results,
+            }
+
+            result = self.jira.get(
+                path=path,
+                params=params,
+            )
+
+            if not isinstance(result, dict):
+                error_msg = f"Unexpected response type from field options API: {type(result)}"
+                logger.error(error_msg)
+                raise ValueError(error_msg)
+
+            # Parse the response using our model
+            options_response = JiraFieldOptionsResponse.from_api_response(
+                result, 
+                max_results=max_results
+            )
+            logger.debug(
+                f"Retrieved {len(options_response.values)} options for field '{field_id}'"
+            )
+            return options_response
+
+        except Exception as e:
+            logger.error(f"Error getting options for field '{field_id}': {str(e)}")
+            raise
+
+    def get_field_context_options(
+        self,
+        field_id: str,
+        context_id: str,
+        start_at: int = 0,
+        max_results: int = 10000,
+    ) -> JiraFieldContextOptionsResponse:
+        """
+        Get options for a custom field within a specific context.
+        This is the most precise way to get field options as they can differ by context.
+
+        Args:
+            field_id: The ID of the field (e.g., 'customfield_10001')
+            context_id: The ID of the context
+            start_at: Starting index for pagination (default: 0)
+            max_results: Maximum number of results per page (default: 10000)
+
+        Returns:
+            JiraFieldContextOptionsResponse with options for the field in the specified context
+
+        Raises:
+            ValueError: If the field_id or context_id is not provided or invalid
+        """
+        if not field_id:
+            raise ValueError("Field ID is required")
+        if not context_id:
+            raise ValueError("Context ID is required")
+
+        if not field_id.startswith("customfield_"):
+            raise ValueError("Field ID must be a custom field (starting with 'customfield_')")
+
+        try:
+            logger.debug(f"Getting context options for field '{field_id}' in context '{context_id}'")
+            
+            # Use different API endpoints for Cloud vs DC/Server
+            if self.config.is_cloud:
+                # Cloud API
+                path = f"/rest/api/3/field/{field_id}/context/{context_id}/option"
+            else:
+                # DC/Server API - context-specific options may not be available
+                # Fall back to general options endpoint with numerical ID only
+                # Extract numerical ID from customfield_XXXXX
+                numerical_id = field_id.replace("customfield_", "")
+                path = f"/rest/api/2/customFields/{numerical_id}/options"
+                logger.warning(f"DC/Server may not support context-specific options for field '{field_id}', using general options")
+            
+            params = {
+                "startAt": start_at,
+                "maxResults": max_results,
+            }
+
+            result = self.jira.get(
+                path=path,
+                params=params,
+            )
+
+            if not isinstance(result, dict):
+                error_msg = f"Unexpected response type from field context options API: {type(result)}"
+                logger.error(error_msg)
+                raise ValueError(error_msg)
+
+            # Parse the response using our model
+            context_options_response = JiraFieldContextOptionsResponse.from_api_response(
+                result, 
+                max_results=max_results
+            )
+            logger.debug(
+                f"Retrieved {len(context_options_response.values)} options for field '{field_id}' in context '{context_id}'"
+            )
+            return context_options_response
+
+        except Exception as e:
+            logger.error(f"Error getting context options for field '{field_id}' in context '{context_id}': {str(e)}")
+            raise

src/mcp_atlassian/models/jira/__init__.py

@@ -25,6 +25,13 @@
     JiraLinkedIssueFields,
 )
 from .project import JiraProject
+from .field_option import (
+    JiraFieldOption,
+    JiraFieldContext,
+    JiraFieldOptionsResponse,
+    JiraFieldContextOptionsResponse,
+    JiraFieldContextsResponse,
+)
 from .search import JiraSearchResult
 from .workflow import JiraTransition
 from .worklog import JiraWorklog
@@ -52,4 +59,10 @@
     "JiraIssueLink",
     "JiraLinkedIssue",
     "JiraLinkedIssueFields",
+    # Field options models
+    "JiraFieldOption",
+    "JiraFieldContext",
+    "JiraFieldOptionsResponse",
+    "JiraFieldContextOptionsResponse",
+    "JiraFieldContextsResponse",
 ]