agentek-youtrack-mcp 1.0.0

package/dist/python/youtrack_mcp/api/issues.py

@@ -0,0 +1,3008 @@
+"""
+YouTrack Issues API client.
+"""
+
+from typing import Any, Dict, List, Optional
+import json
+import logging
+import re
+
+from pydantic import BaseModel, Field
+
+from youtrack_mcp.api.client import YouTrackClient, YouTrackAPIError
+
+logger = logging.getLogger(__name__)
+
+
+class AttachmentNotFoundError(ValueError):
+    """Raised when an attachment is not found in an issue."""
+
+    pass
+
+
+class Issue(BaseModel):
+    """Model for a YouTrack issue."""
+
+    id: str
+    summary: Optional[str] = None
+    description: Optional[str] = None
+    created: Optional[int] = None
+    updated: Optional[int] = None
+    project: Optional[Dict[str, Any]] = Field(default_factory=dict)
+    reporter: Optional[Dict[str, Any]] = None
+    assignee: Optional[Dict[str, Any]] = None
+    custom_fields: Optional[List[Dict[str, Any]]] = Field(default_factory=list)
+    attachments: Optional[List[Dict[str, Any]]] = Field(default_factory=list)
+
+    model_config = {
+        "extra": "allow",  # Allow extra fields from the API
+        "populate_by_name": True,  # Allow population by field name (helps with aliases)
+        "validate_assignment": False,  # Less strict validation for attribute assignment
+        "protected_namespaces": (),  # Don't protect any namespaces
+    }
+
+    @classmethod
+    def model_validate(cls, obj, *args, **kwargs):
+        """Override model_validate to handle various input formats."""
+        try:
+            # Try standard validation
+            return super().model_validate(obj, *args, **kwargs)
+        except Exception as e:
+            # Fall back to more permissive validation
+            if isinstance(obj, dict):
+                # Ensure ID is present
+                if "id" not in obj and obj.get("$type") == "Issue":
+                    # Try to find an ID from other fields or generate placeholder
+                    obj["id"] = obj.get(
+                        "idReadable", str(obj.get("created", "unknown-id"))
+                    )
+
+                # Create issue with minimal validated data
+                return cls(
+                    id=obj.get("id", "unknown"),
+                    summary=obj.get("summary", "No summary"),
+                    description=obj.get("description", ""),
+                    created=obj.get("created"),
+                    updated=obj.get("updated"),
+                    project=obj.get("project", {}),
+                    reporter=obj.get("reporter"),
+                    assignee=obj.get("assignee"),
+                    custom_fields=obj.get("customFields", []),
+                )
+
+            # If obj isn't even a dict, raise the original error
+            raise
+
+
+class IssuesClient:
+    """Client for interacting with YouTrack Issues API."""
+
+    # Well-known custom field names that map to version/sprint bundles
+    # (matched case-insensitively).
+    _VERSION_FIELD_NAMES = [
+        'fix versions', 'fix version', 'affected versions', 'affected version',
+        'sprints', 'sprint', 'milestone', 'release',
+    ]
+
+    def __init__(self, client: YouTrackClient):
+        """
+        Initialize the Issues API client.
+
+        Args:
+            client: The YouTrack API client
+        """
+        self.client = client
+
+    def get_issue(self, issue_id: str) -> Issue:
+        """
+        Get an issue by ID.
+
+        Args:
+            issue_id: The issue ID or readable ID (e.g., PROJECT-123)
+
+        Returns:
+            The issue data
+        """
+        try:
+            # Get issue data
+            response = self.client.get(f"issues/{issue_id}")
+
+            # If the response doesn't have all needed fields, fetch more details
+            if (
+                isinstance(response, dict)
+                and response.get("$type") == "Issue"
+                and "summary" not in response
+            ):
+                # Get additional fields we need including attachments
+                fields = "id,idReadable,summary,description,created,updated,project(id,shortName),reporter,assignee,customFields,attachments(id,name,url,mimeType,size)"
+                try:
+                    detailed_response = self.client.get(
+                        f"issues/{issue_id}?fields={fields}"
+                    )
+                except Exception as e:
+                    logger.warning(f"Failed to get detailed issue data: {e}")
+                    detailed_response = response
+            else:
+                detailed_response = response
+
+            # Ensure the ID field is present
+            if (
+                isinstance(detailed_response, dict)
+                and "id" not in detailed_response
+                and detailed_response.get("$type") == "Issue"
+            ):
+                detailed_response["id"] = issue_id
+
+            try:
+                # Try to validate the model
+                return Issue.model_validate(detailed_response)
+            except Exception as validation_error:
+                # If validation fails, create a more flexible issue object
+                logger.warning(
+                    f"Issue validation error: {validation_error}. Creating issue with minimal data."
+                )
+
+                if isinstance(detailed_response, dict):
+                    # Extract key fields if possible
+                    summary = detailed_response.get(
+                        "summary", "Unknown summary"
+                    )
+                    description = detailed_response.get("description", "")
+
+                    # Create a basic issue with the available data
+                    issue = Issue(
+                        id=issue_id, summary=summary, description=description
+                    )
+
+                    # Add any other fields that might be useful
+                    for field in [
+                        "created",
+                        "updated",
+                        "project",
+                        "reporter",
+                        "assignee",
+                        "attachments",
+                    ]:
+                        if field in detailed_response:
+                            setattr(issue, field, detailed_response[field])
+
+                    return issue
+                else:
+                    # If response is not even a dict, create a minimal issue
+                    return Issue(id=issue_id, summary=f"Issue {issue_id}")
+
+        except Exception as e:
+            # Log the full error with traceback
+            logger.exception(f"Error retrieving issue {issue_id}")
+            # Create minimal issue to avoid breaking calls
+            return Issue(id=issue_id, summary=f"Error: {str(e)[:100]}...")
+
+    def create_issue(
+        self,
+        project_id: str,
+        summary: str,
+        description: Optional[str] = None,
+        additional_fields: Optional[Dict[str, Any]] = None,
+    ) -> Issue:
+        """
+        Create a new issue.
+
+        Args:
+            project_id: The ID of the project
+            summary: The issue summary
+            description: The issue description
+            additional_fields: Additional fields to set on the issue
+
+        Returns:
+            The created issue data
+        """
+        # Make sure we have valid input data
+        if not project_id:
+            raise ValueError("Project ID is required")
+        if not summary:
+            raise ValueError("Summary is required")
+
+        # Format request data according to YouTrack API requirements
+        # Note: YouTrack API requires a specific format for some fields
+        data = {"project": {"id": project_id}, "summary": summary}
+
+        if description:
+            data["description"] = description
+
+        if additional_fields:
+            data.update(additional_fields)
+
+        try:
+            # For debugging
+            logger.info(f"Creating issue with data: {json.dumps(data)}")
+
+            # Post directly with the json parameter to ensure correct format
+            url = "issues"
+            response = self.client.session.post(
+                f"{self.client.base_url}/{url}",
+                json=data,
+                headers={
+                    "Content-Type": "application/json",
+                    "Accept": "application/json",
+                },
+            )
+
+            # Handle the response
+            if response.status_code >= 400:
+                error_msg = f"Error creating issue: {response.status_code}"
+                try:
+                    error_content = response.json()
+                    error_msg += f" - {json.dumps(error_content)}"
+                except Exception:
+                    error_msg += f" - {response.text}"
+
+                logger.error(error_msg)
+                raise YouTrackAPIError(
+                    error_msg, response.status_code, response
+                )
+
+            # Process successful response
+            try:
+                result = response.json()
+                return Issue.model_validate(result)
+            except Exception as e:
+                logger.error(f"Error parsing response: {str(e)}")
+                # Return raw response if we can't parse it
+                return Issue(
+                    id=str(response.status_code),
+                    summary="Created successfully",
+                )
+
+        except Exception as e:
+            import logging
+
+            logging.getLogger(__name__).error(
+                f"Error creating issue: {str(e)}, Data: {data}"
+            )
+            raise
+
+    def update_issue(
+        self,
+        issue_id: str,
+        summary: Optional[str] = None,
+        description: Optional[str] = None,
+        additional_fields: Optional[Dict[str, Any]] = None,
+    ) -> Issue:
+        """
+        Update an existing issue.
+
+        Args:
+            issue_id: The issue ID or readable ID
+            summary: The new issue summary
+            description: The new issue description
+            additional_fields: Additional fields to update
+
+        Returns:
+            The updated issue data
+        """
+        data = {}
+
+        if summary is not None:
+            data["summary"] = summary
+
+        if description is not None:
+            data["description"] = description
+
+        if additional_fields:
+            data.update(additional_fields)
+
+        if not data:
+            # Nothing to update
+            return self.get_issue(issue_id)
+
+        response = self.client.post(f"issues/{issue_id}", data=data)
+        return Issue.model_validate(response)
+
+    def update_issue_custom_fields(
+        self,
+        issue_id: str,
+        custom_fields: Dict[str, Any],
+        validate: bool = True,
+        use_commands: bool = False,  # Changed default to False - direct API works better
+    ) -> Dict[str, Any]:
+        """
+        Update multiple custom fields on an issue using proven working approach.
+
+        Based on successful testing with this YouTrack instance:
+        - Direct Field Update API works reliably for state transitions  
+        - Command API may be blocked by workflow restrictions
+        - Uses direct API as primary method with command fallback
+
+        Args:
+            issue_id: The issue identifier
+            custom_fields: Dictionary of field names and values to update
+            validate: Whether to validate field values before updating
+            use_commands: Whether to try command-based approach as fallback (default: False)
+
+        Returns:
+            Updated issue data
+        """
+        try:
+            # First, get current issue state to detect state machine workflows
+            issue_data = self.get_issue(issue_id)
+            
+            # Check if we're updating State field and if it uses state machines
+            state_field_update = None
+            other_fields = {}
+            
+            for field_name, field_value in custom_fields.items():
+                if field_name.lower() == 'state':
+                    state_field_update = (field_name, field_value)
+                else:
+                    other_fields[field_name] = field_value
+            
+            # Handle state transitions with enhanced workflow support
+            if state_field_update:
+                field_name, target_state = state_field_update
+                success = self._handle_state_transition(issue_id, target_state, use_commands)
+                
+                # Only try command-based fallback if we haven't already tried it
+                if not success and not use_commands:
+                    logger.info(f"Direct state update failed, trying command-based approach for issue {issue_id}")
+                    success = self._handle_state_transition(issue_id, target_state, use_commands=True)
+                
+                if not success:
+                    raise YouTrackAPIError(f"Failed to transition issue {issue_id} to state '{target_state}'. This may be due to workflow restrictions, permissions, or state machine guard conditions.")
+            
+            # Handle other custom fields using existing logic
+            if other_fields:
+                try:
+                    self._update_other_custom_fields(issue_id, other_fields, validate, use_commands)
+                except YouTrackAPIError as e:
+                    if "405" in str(e) and not use_commands:
+                        # 405 Method Not Allowed - try command-based approach
+                        logger.info(f"Direct API update failed with 405, trying command-based approach for issue {issue_id}")
+                        self._update_other_custom_fields(issue_id, other_fields, validate, use_commands=True)
+                    else:
+                        raise
+            
+            # Return updated issue data
+            return self.get_issue(issue_id)
+
+        except Exception as e:
+            logger.exception(f"Error updating custom fields for issue {issue_id}")
+            raise YouTrackAPIError(f"Failed to update custom fields: {str(e)}")
+    
+    def _handle_state_transition(self, issue_id: str, target_state: str, use_commands: bool = False) -> bool:
+        """
+        Handle state transitions using multiple approaches based on YouTrack configuration.
+        
+        This method tries different approaches in order:
+        1. Direct Field Update API (works for some fields, may fail due to workflow restrictions)
+        2. Command-based approach (more reliable but can be blocked by permissions)
+        3. Event-based transitions for state machine workflows
+        
+        Args:
+            issue_id: The issue identifier
+            target_state: Target state name
+            use_commands: Whether to prioritize command-based approach
+            
+        Returns:
+            True if transition succeeded, False otherwise
+        """
+        try:
+            # Method 1: Direct Field Update (PROVEN TO WORK in testing)
+            logger.info(f"Attempting direct field update for issue {issue_id} to state '{target_state}'")
+            success = self._apply_direct_state_update(issue_id, target_state)
+            
+            if success:
+                logger.info(f"Direct field update succeeded for issue {issue_id}")
+                return True
+            
+            # Method 2: Fallback to command-based approach if enabled
+            if use_commands:
+                logger.info(f"Direct update failed, trying command-based approach for issue {issue_id}")
+                try:
+                    command_data = {
+                        "query": f"State \"{target_state}\"",
+                        "issues": [{"id": issue_id}]
+                    }
+                    
+                    logger.info(f"Applying state transition command 'State \"{target_state}\"' to issue {issue_id}")
+                    self.client.post("commands", data=command_data)
+                    logger.info(f"Command-based transition succeeded for issue {issue_id}")
+                    return True
+                    
+                except Exception as cmd_error:
+                    logger.warning(f"Command-based approach failed: {cmd_error}")
+            
+            # Method 3: Try state machine detection and event-based transitions
+            logger.info(f"Trying state machine event-based approach for issue {issue_id}")
+            try:
+                # Query possible transitions (as recommended in analysis)
+                issue_fields = self.client.get(f"issues/{issue_id}/customFields?fields=name,possibleEvents(id,presentation),value(name),$type")
+                
+                state_field = None
+                for field in issue_fields:
+                    if field.get('name', '').lower() == 'state':
+                        state_field = field
+                        break
+                
+                if state_field:
+                    field_type = state_field.get('$type', '')
+                    possible_events = state_field.get('possibleEvents', [])
+                    
+                    # Check if this is a state machine workflow
+                    if field_type == 'StateMachineIssueCustomField' and possible_events:
+                        # Use event-based transition
+                        logger.info(f"Detected state machine workflow for issue {issue_id}")
+                        return self._apply_state_machine_transition(issue_id, target_state, possible_events)
+                
+            except Exception as sm_error:
+                logger.warning(f"State machine detection failed: {sm_error}")
+            
+            # All methods failed
+            logger.error(f"All state transition methods failed for issue {issue_id} to state '{target_state}'")
+            return False
+                     
+        except Exception as e:
+            logger.error(f"State transition failed for issue {issue_id} to state '{target_state}': {e}")
+            return False
+    
+    def _apply_state_machine_transition(self, issue_id: str, target_state: str, possible_events: List[Dict]) -> bool:
+        """
+        Apply state machine-based transition using events.
+        
+        Args:
+            issue_id: The issue identifier
+            target_state: Target state name
+            possible_events: Available transition events
+            
+        Returns:
+            True if transition succeeded, False otherwise
+        """
+        try:
+            # Find the event that leads to the target state
+            target_event = None
+            for event in possible_events:
+                # This would need more sophisticated matching logic
+                # based on the actual event structure in your YouTrack instance
+                event_presentation = event.get('presentation', '').lower()
+                if target_state.lower() in event_presentation:
+                    target_event = event
+                    break
+            
+            if target_event:
+                # Apply event-based transition
+                update_data = {
+                    "customFields": [{
+                        "$type": "StateMachineIssueCustomField",
+                        "name": "State",
+                        "event": {
+                            "$type": "Event",
+                            "id": target_event.get('id')
+                        }
+                    }]
+                }
+                
+                self.client.post(f"issues/{issue_id}", data=update_data)
+                logger.info(f"Applied state machine event '{target_event.get('id')}' to issue {issue_id}")
+                return True
+            else:
+                logger.warning(f"No suitable event found for state transition to '{target_state}'")
+                return False
+                    
+        except Exception as e:
+            logger.error(f"State machine transition failed: {e}")
+            return False
+    
+    def _apply_direct_state_update(self, issue_id: str, target_state: str) -> bool:
+        """
+        Apply direct state field update using proven working format.
+        
+        Based on successful testing, the working format is:
+        {"customFields": [{"name": "State", "value": "In Progress"}]}
+        
+        NOT complex objects or ID references.
+        """
+        try:
+            # Use the proven simple string format that works
+            update_data = {
+                "customFields": [{
+                    "name": "State",
+                    "value": target_state  # Simple string value - this is what works!
+                }]
+            }
+            
+            logger.info(f"Applying direct state update to issue {issue_id}: State -> '{target_state}'")
+            self.client.post(f"issues/{issue_id}", data=update_data)
+            
+            logger.info(f"Direct state update successful for issue {issue_id}")
+            return True
+            
+        except Exception as e:
+            logger.warning(f"Direct state update failed for issue {issue_id}: {e}")
+            return False
+    
+    def _update_other_custom_fields(self, issue_id: str, custom_fields: Dict[str, Any], validate: bool, use_commands: bool) -> None:
+        """
+        Update non-state custom fields, prioritizing direct field updates.
+        
+        Based on successful testing, uses simple values where possible:
+        - Strings: "Critical", "admin", "Bug"  
+        - NOT complex objects: {"name": "Critical", "id": "123"}
+        
+        Args:
+            issue_id: Issue identifier
+            custom_fields: Dictionary of field names and values
+            validate: Whether to validate field values  
+            use_commands: Whether to try command-based approach as fallback
+        """
+        # Method 1: Direct field update approach (primary method)
+        try:
+            # Always get issue data to extract project ID for schema lookups
+            issue_data = self.get_issue(issue_id)
+            
+            # Validate fields if requested
+            if validate:
+                project_id = None
+                if hasattr(issue_data, 'project') and issue_data.project:
+                    if isinstance(issue_data.project, dict):
+                        project_id = issue_data.project.get('id')
+                    else:
+                        project_id = getattr(issue_data.project, 'id', None)
+                
+                if project_id:
+                    for field_name, field_value in custom_fields.items():
+                        is_valid = self._validate_custom_field_value(project_id, field_name, field_value)
+                        if not is_valid:
+                            raise YouTrackAPIError(f"Custom field validation failed for '{field_name}': '{field_value}' is not a valid value")
+                else:
+                    logger.warning("Could not get project ID for validation, skipping validation")
+            
+            # YouTrack requires proper object types with actual IDs for custom field updates
+            # Try to get project ID for schema lookups (optional for enhanced object creation)
+            project_id = None
+            
+            if hasattr(issue_data, 'project') and issue_data.project:
+                if isinstance(issue_data.project, dict):
+                    project_id = issue_data.project.get('id')
+                else:
+                    project_id = getattr(issue_data.project, 'id', None)
+            
+            # If we can't get project ID, fall back to simple $type approach
+            if not project_id:
+                logger.warning("Could not determine project ID for enhanced object creation, using simple $type approach")
+                use_simple_approach = True
+            else:
+                use_simple_approach = False
+            
+            update_data = {"customFields": []}
+            
+            for field_name, raw_field_value in custom_fields.items():
+                # Normalize complex object formats to simple strings first
+                field_value = self._normalize_field_value(raw_field_value)
+                
+                # Determine field type and construct proper object with actual ID
+                if use_simple_approach:
+                    # Fallback to simple $type approach when project ID is not available
+                    if field_name.lower() in ['state']:
+                        field_type = "StateIssueCustomField"
+                    elif field_name.lower() in ['priority', 'type']:
+                        field_type = "SingleEnumIssueCustomField"
+                    elif field_name.lower() in ['assignee', 'reporter']:
+                        field_type = "SingleUserIssueCustomField"
+                    elif field_name.lower() in ['estimation', 'spent time']:
+                        field_type = "PeriodIssueCustomField"
+                    else:
+                        field_type = "SingleEnumIssueCustomField"
+                    
+                    field_data = {
+                        "$type": field_type,
+                        "name": field_name,
+                        "value": field_value
+                    }
+                else:
+                    # Enhanced approach with proper YouTrack objects and actual IDs
+                    # Handle Estimation with proper PeriodValue format
+                    if field_name.lower() in ['estimation']:
+                        # Estimation REQUIRES PeriodValue format, not simple strings
+                        field_data = self._create_period_field_object(field_name, field_value)
+                    elif field_name.lower() in ['state']:
+                        field_data = self._create_state_field_object(project_id, field_name, field_value)
+                    elif field_name.lower() in ['priority', 'type']:
+                        field_data = self._create_enum_field_object(project_id, field_name, field_value)
+                    elif field_name.lower() in ['assignee', 'reporter']:
+                        field_data = self._create_user_field_object(field_name, field_value)
+                    elif field_name.lower() in ['spent time']:
+                        field_data = self._create_period_field_object(field_name, field_value)
+                    elif field_name.lower() in self._VERSION_FIELD_NAMES:
+                        # Detect version/sprint fields by well-known name
+                        field_data = self._create_version_field_object(project_id, field_name, field_value, multi=True)
+                    else:
+                        # Query the schema to detect version/sprint fields
+                        value_type = self._get_field_value_type(project_id, field_name)
+                        if value_type == "version":
+                            field_data = self._create_version_field_object(project_id, field_name, field_value, multi=True)
+                        else:
+                            # Default to enum for unknown fields
+                            field_data = self._create_enum_field_object(project_id, field_name, field_value)
+                
+                if field_data:
+                    update_data["customFields"].append(field_data)
+            
+            logger.info(f"Updating custom fields for issue {issue_id} using proper YouTrack objects")
+            logger.info(f"Update payload: {json.dumps(update_data, indent=2)}")
+            self.client.post(f"issues/{issue_id}", data=update_data)
+            logger.info(f"Direct field update succeeded for issue {issue_id}")
+            
+        except Exception as direct_error:
+            logger.warning(f"Direct field update failed: {direct_error}")
+            
+            # Method 2: Fallback to command-based approach if enabled
+            if use_commands:
+                logger.info(f"Trying command-based approach as fallback for issue {issue_id}")
+                try:
+                    self._apply_commands_update(issue_id, custom_fields)
+                    logger.info(f"Command-based update succeeded for issue {issue_id}")
+                    return
+                except Exception as cmd_error:
+                    logger.warning(f"Command-based approach also failed: {cmd_error}")
+            
+            # If both direct and command approaches fail, raise the original error with full details
+            error_msg = f"Direct field update failed"
+            if hasattr(direct_error, 'response') and hasattr(direct_error.response, 'json'):
+                try:
+                    error_details = direct_error.response.json()
+                    if 'error_description' in error_details:
+                        error_msg += f": {error_details['error_description']}"
+                    elif 'error' in error_details:
+                        error_msg += f": {error_details['error']}"
+                    else:
+                        error_msg += f": {str(direct_error)}"
+                except:
+                    error_msg += f": {str(direct_error)}"
+            else:
+                error_msg += f": {str(direct_error)}"
+            
+            raise YouTrackAPIError(error_msg)
+
+    def _create_enum_field_object(self, project_id: str, field_name: str, field_value: Any) -> Dict[str, Any]:
+        """Create proper EnumBundleElement object with actual ID."""
+        try:
+            # Normalize field value first
+            normalized_value = self._normalize_field_value(field_value)
+            
+            # Get allowed values to find the actual ID
+            from youtrack_mcp.api.projects import ProjectsClient
+            projects_client = ProjectsClient(self.client)
+            allowed_values = projects_client.get_custom_field_allowed_values(project_id, field_name)
+            
+            # Find the matching value by name (case-insensitive)
+            value_id = None
+            for value in allowed_values:
+                if value.get('name', '').lower() == normalized_value.lower():
+                    value_id = value.get('id')
+                    break
+            
+            if value_id:
+                return {
+                    "$type": "SingleEnumIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "EnumBundleElement",
+                        "id": value_id,
+                        "name": normalized_value
+                    }
+                }
+            else:
+                logger.warning(f"Could not find ID for enum value '{field_value}' in field '{field_name}', trying simple enum object")
+                # Try simple enum object format if ID lookup fails
+                return {
+                    "$type": "SingleEnumIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "EnumBundleElement",
+                        "name": normalized_value
+                    }
+                }
+        except Exception as e:
+            logger.warning(f"Error creating enum field object for '{field_name}': {e}, trying simple enum object")
+            # Fallback to simple enum object (no ID)
+            return {
+                "$type": "SingleEnumIssueCustomField",
+                "name": field_name,
+                "value": {
+                    "$type": "EnumBundleElement",
+                    "name": normalized_value
+                }
+            }
+
+    def _create_state_field_object(self, project_id: str, field_name: str, field_value: Any) -> Dict[str, Any]:
+        """Create proper StateBundleElement object with actual ID."""
+        try:
+            # Normalize field value first
+            normalized_value = self._normalize_field_value(field_value)
+            
+            # Get allowed values to find the actual ID
+            from youtrack_mcp.api.projects import ProjectsClient
+            projects_client = ProjectsClient(self.client)
+            allowed_values = projects_client.get_custom_field_allowed_values(project_id, field_name)
+            
+            # Find the matching state by name (case-insensitive)
+            state_id = None
+            for value in allowed_values:
+                if value.get('name', '').lower() == normalized_value.lower():
+                    state_id = value.get('id')
+                    break
+            
+            if state_id:
+                return {
+                    "$type": "StateIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "StateBundleElement",
+                        "id": state_id,
+                        "name": field_value
+                    }
+                }
+            else:
+                logger.warning(f"Could not find ID for state value '{field_value}' in field '{field_name}', using simple value")
+                return {
+                    "$type": "StateIssueCustomField",
+                    "name": field_name,
+                    "value": field_value
+                }
+        except Exception as e:
+            logger.warning(f"Error creating state field object for '{field_name}': {e}, using simple value")
+            return {
+                "$type": "StateIssueCustomField",
+                "name": field_name,
+                "value": field_value
+            }
+
+    def _create_user_field_object(self, field_name: str, field_value: Any) -> Dict[str, Any]:
+        """Create proper User object with actual ID."""
+        try:
+            # Normalize field value first
+            normalized_value = self._normalize_field_value(field_value)
+            
+            # Get user ID by login
+            from youtrack_mcp.api.users import UsersClient
+            users_client = UsersClient(self.client)
+            user_data = users_client.get_user(normalized_value)
+            
+            if user_data and hasattr(user_data, 'id') and user_data.id:
+                return {
+                    "$type": "SingleUserIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "User",
+                        "id": user_data.id,
+                        "login": normalized_value
+                    }
+                }
+            else:
+                logger.warning(f"Could not find user ID for login '{field_value}', using simple value")
+                return {
+                    "$type": "SingleUserIssueCustomField",
+                    "name": field_name,
+                    "value": field_value
+                }
+        except Exception as e:
+            logger.warning(f"Error creating user field object for '{field_name}': {e}, using simple value")
+            return {
+                "$type": "SingleUserIssueCustomField",
+                "name": field_name,
+                "value": field_value
+            }
+
+    def _create_period_field_object(self, field_name: str, field_value: Any) -> Dict[str, Any]:
+        """Create proper period field object with PeriodValue format."""
+        try:
+            # Normalize field value first
+            normalized_value = self._normalize_field_value(field_value)
+            
+            # Convert simple time strings to proper PeriodValue format
+            # Examples: "4h" -> 240 minutes, "30m" -> 30 minutes, "2h 30m" -> 150 minutes
+            
+            minutes = self._parse_time_to_minutes(normalized_value)
+            
+            if minutes is not None:
+                return {
+                    "$type": "PeriodIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "PeriodValue",
+                        "minutes": minutes
+                    }
+                }
+            else:
+                # Fallback to simple value if parsing fails
+                logger.warning(f"Could not parse period value '{field_value}' for field '{field_name}', using simple value")
+                return {
+                    "$type": "PeriodIssueCustomField",
+                    "name": field_name,
+                    "value": field_value
+                }
+        except Exception as e:
+            logger.warning(f"Error creating period field object for '{field_name}': {e}, using simple value")
+            return {
+                "$type": "PeriodIssueCustomField",
+                "name": field_name,
+                "value": field_value
+            }
+    
+    def _parse_time_to_minutes(self, time_str: str) -> Optional[int]:
+        """Parse time string to minutes for PeriodValue."""
+        try:
+            time_str = time_str.strip().lower()
+            total_minutes = 0
+            
+            # Handle formats like "4h", "30m", "2h 30m", "1h30m"
+            
+            # Extract hours
+            hours_match = re.search(r'(\d+)\s*h', time_str)
+            if hours_match:
+                total_minutes += int(hours_match.group(1)) * 60
+            
+            # Extract minutes
+            minutes_match = re.search(r'(\d+)\s*m', time_str)
+            if minutes_match:
+                total_minutes += int(minutes_match.group(1))
+            
+            # If no h or m found, assume it's just minutes
+            if not hours_match and not minutes_match:
+                # Try to parse as plain number (minutes)
+                if time_str.isdigit():
+                    total_minutes = int(time_str)
+                else:
+                    return None
+            
+            return total_minutes if total_minutes > 0 else None
+            
+        except Exception as e:
+            logger.debug(f"Failed to parse time string '{time_str}': {e}")
+            return None
+
+    def _apply_commands_update(self, issue_id: str, custom_fields: Dict[str, Any]) -> None:
+        """
+        Apply custom field updates using the command-based approach.
+        This method is a fallback and might not be as reliable as direct field updates.
+        """
+        try:
+            command_data = {"query": "updateCustomFields"}
+            for field_name, field_value in custom_fields.items():
+                command_data["query"] += f" {field_name} {field_value}"
+            
+            command_data["issues"] = [{"id": issue_id}]
+            
+            logger.info(f"Applying command-based update for issue {issue_id} with query: {command_data['query']}")
+            self.client.post("commands", data=command_data)
+            logger.info(f"Command-based update succeeded for issue {issue_id}")
+        except Exception as e:
+            logger.warning(f"Command-based update failed: {e}")
+            raise
+
+    def get_issue_custom_fields(self, issue_id: str) -> Dict[str, Any]:
+        """
+        Get all custom fields for a specific issue.
+
+        Args:
+            issue_id: The issue ID or readable ID
+
+        Returns:
+            Dictionary of custom field name-value pairs
+        """
+        fields = "customFields(id,name,value($type,name,text,id,login))"
+        response = self.client.get(f"issues/{issue_id}?fields={fields}")
+        
+        custom_fields = {}
+        if "customFields" in response:
+            for field in response["customFields"]:
+                field_name = field.get("name", "")
+                field_value = self._extract_custom_field_value(field.get("value"))
+                custom_fields[field_name] = field_value
+        
+        return custom_fields
+
+    def validate_custom_field_value(
+        self, 
+        project_id: str, 
+        field_name: str, 
+        field_value: Any
+    ) -> Dict[str, Any]:
+        """
+        Validate a custom field value against project schema.
+
+        Args:
+            project_id: The project ID
+            field_name: The custom field name
+            field_value: The value to validate
+
+        Returns:
+            Dictionary with validation result and details
+        """
+        try:
+            is_valid = self._validate_custom_field_value(project_id, field_name, field_value)
+            
+            if is_valid:
+                return {
+                    "valid": True,
+                    "field": field_name,
+                    "value": field_value,
+                    "message": "Valid"
+                }
+            else:
+                # Get available values for better error messages
+                available_values = self._get_custom_field_allowed_values(project_id, field_name)
+                suggestion = f"Available values: {', '.join(map(str, available_values))}" if available_values else "Check field configuration"
+                
+                return {
+                    "valid": False,
+                    "field": field_name,
+                    "value": field_value,
+                    "error": f"Invalid value '{field_value}' for field '{field_name}'",
+                    "suggestion": suggestion
+                }
+        except Exception as e:
+            return {
+                "valid": False,
+                "field": field_name,
+                "value": field_value,
+                "error": f"Validation error: {str(e)}",
+                "suggestion": "Check field name and project configuration"
+            }
+
+    def batch_update_custom_fields(
+        self,
+        updates: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """
+        Update custom fields for multiple issues in a single operation.
+
+        Args:
+            updates: List of update dictionaries with format:
+                    [{"issue_id": "DEMO-123", "fields": {"Priority": "High"}}]
+
+        Returns:
+            List of update results with success/error status
+        """
+        results = []
+        
+        for update in updates:
+            issue_id = update.get("issue_id")
+            fields = update.get("fields", {})
+            
+            if not issue_id:
+                results.append({
+                    "issue_id": None,
+                    "status": "error",
+                    "error": "Missing issue_id in update"
+                })
+                continue
+            
+            if not fields:
+                results.append({
+                    "issue_id": issue_id,
+                    "status": "skipped",
+                    "message": "No fields to update"
+                })
+                continue
+            
+            try:
+                updated_issue = self.update_issue_custom_fields(
+                    issue_id=issue_id,
+                    custom_fields=fields,
+                    validate=update.get("validate", True)
+                )
+                
+                results.append({
+                    "issue_id": issue_id,
+                    "status": "success",
+                    "updated_fields": list(fields.keys()),
+                    "issue_data": updated_issue.model_dump() if hasattr(updated_issue, 'model_dump') else updated_issue
+                })
+                
+            except Exception as e:
+                results.append({
+                    "issue_id": issue_id,
+                    "status": "error",
+                    "error": str(e),
+                    "attempted_fields": list(fields.keys())
+                })
+        
+        return results
+
+    def search_issues(self, query: str, limit: int = 10) -> List[Issue]:
+        """
+        Search for issues using YouTrack query language.
+
+        Args:
+            query: The search query
+            limit: Maximum number of issues to return
+
+        Returns:
+            List of matching issues
+        """
+        # Request additional fields to ensure we get summary
+        fields = "id,idReadable,summary,description,created,updated,project,reporter,assignee,customFields"
+        params = {"query": query, "$top": limit, "fields": fields}
+        response = self.client.get("issues", params=params)
+
+        issues = []
+        if isinstance(response, list):
+            for issue_data in response:
+                try:
+                    issues.append(Issue.model_validate(issue_data))
+                except Exception as e:
+                    logger.warning(f"Error validating issue: {e}")
+                    # Create a basic issue with id
+                    issue_id = issue_data.get(
+                        "id", str(issue_data.get("created", "unknown"))
+                    )
+                    issues.append(
+                        Issue(
+                            id=issue_id,
+                            summary=issue_data.get(
+                                "summary", f"Issue {issue_id}"
+                            ),
+                        )
+                    )
+
+        return issues
+
+    def add_comment(self, issue_id: str, text: str) -> Dict[str, Any]:
+        """
+        Add a comment to an issue.
+
+        Args:
+            issue_id: The issue ID or readable ID
+            text: The comment text
+
+        Returns:
+            The created comment data
+        """
+        data = {"text": text}
+        return self.client.post(f"issues/{issue_id}/comments", data=data)
+
+    def get_attachment_content(
+        self, issue_id: str, attachment_id: str
+    ) -> bytes:
+        """
+        Get the content of an attachment with file size validation.
+
+        Args:
+            issue_id: The issue ID or readable ID
+            attachment_id: The attachment ID
+
+        Returns:
+            The attachment content as bytes
+
+        Raises:
+            ValueError: If attachment not found or file too large
+            YouTrackAPIError: If API request fails
+        """
+        # First, get the attachment metadata to get the URL and size
+        issue_response = self.client.get(
+            f"issues/{issue_id}?fields=attachments(id,url,size,name,mimeType)"
+        )
+
+        # Find the attachment with the matching ID
+        attachment_info = None
+        if "attachments" in issue_response:
+            for attachment in issue_response["attachments"]:
+                if attachment.get("id") == attachment_id:
+                    attachment_info = attachment
+                    break
+
+        if not attachment_info:
+            raise ValueError(
+                f"Attachment {attachment_id} not found in issue {issue_id}"
+            )
+
+        # Check file size limit for base64 encoding
+        # Base64 encoding increases size by ~33%, so for 1MB base64 limit, max original size is ~750KB
+        MAX_ORIGINAL_SIZE = 750 * 1024  # 750KB original file
+        MAX_BASE64_SIZE = (
+            1024 * 1024
+        )  # 1MB after base64 encoding (Claude Desktop limit)
+
+        file_size = attachment_info.get("size", 0)
+        filename = attachment_info.get("name", attachment_id)
+        mime_type = attachment_info.get("mimeType", "unknown")
+
+        if file_size > MAX_ORIGINAL_SIZE:
+            # Calculate what the base64 size would be
+            estimated_base64_size = int(file_size * 1.33)
+            raise ValueError(
+                f"Attachment '{filename}' ({mime_type}) is too large "
+                f"({file_size:,} bytes → ~{estimated_base64_size:,} bytes after base64 encoding). "
+                f"Maximum allowed: {MAX_ORIGINAL_SIZE:,} bytes original (~{MAX_BASE64_SIZE:,} bytes base64)."
+            )
+
+        attachment_url = attachment_info.get("url")
+        if not attachment_url:
+            raise ValueError(
+                f"No download URL found for attachment {attachment_id}"
+            )
+
+        # The URL in the attachment data is relative to the base URL
+        if attachment_url.startswith("/"):
+            attachment_url = attachment_url[1:]  # Remove leading slash
+
+        # Construct the full URL
+        base_url = self.client.base_url
+        if base_url.endswith("/api"):
+            base_url = base_url[:-4]  # Remove '/api' suffix
+
+        full_url = f"{base_url}/{attachment_url}"
+
+        # Make the request to get the attachment content
+        from youtrack_mcp.api.client import YouTrackAPIError
+
+        response = self.client.session.get(full_url)
+
+        # Check for errors
+        if response.status_code >= 400:
+            error_msg = (
+                f"Error getting attachment content: {response.status_code}"
+            )
+            raise YouTrackAPIError(error_msg, response.status_code, response)
+
+        # Double-check the actual content size
+        content_length = len(response.content)
+        if content_length > MAX_ORIGINAL_SIZE:
+            estimated_base64_size = int(content_length * 1.33)
+            raise ValueError(
+                f"Downloaded content size ({content_length:,} bytes → ~{estimated_base64_size:,} bytes base64) "
+                f"exceeds maximum allowed size ({MAX_ORIGINAL_SIZE:,} bytes original). "
+                f"The file may have been modified since metadata was fetched."
+            )
+
+        # Return the binary content
+        return response.content
+
+    def delete_attachment(self, issue_id: str, attachment_id: str) -> None:
+        """
+        Delete an attachment from an issue.
+
+        Args:
+            issue_id: The issue ID or readable ID
+            attachment_id: The attachment ID to delete
+
+        Raises:
+            AttachmentNotFoundError: If attachment not found
+            YouTrackAPIError: If API request fails (e.g., insufficient permissions)
+        """
+        # First verify the attachment exists
+        issue_response = self.client.get(
+            f"issues/{issue_id}?fields=attachments(id,name)"
+        )
+
+        # Check if attachment exists
+        attachment_found = False
+        if "attachments" in issue_response:
+            for attachment in issue_response["attachments"]:
+                if attachment.get("id") == attachment_id:
+                    attachment_found = True
+                    break
+
+        if not attachment_found:
+            raise AttachmentNotFoundError(
+                f"Attachment {attachment_id} not found in issue {issue_id}"
+            )
+
+        # Delete the attachment
+        self.client.delete(f"issues/{issue_id}/attachments/{attachment_id}")
+
+    def _get_internal_id(self, issue_id: str) -> str:
+        """Convert issue ID to internal format if needed."""
+        try:
+            internal_id = self.client.get(f"issues/{issue_id}?fields=id")["id"]
+            return internal_id
+        except Exception:
+            # If that fails, assume the issue_id is already internal
+            return issue_id
+
+    def _get_readable_id(self, issue_id: str) -> str:
+        """
+        Convert an internal issue ID (like 3-37) to readable ID (like DEMO-37).
+        If it's already a readable ID, return as-is.
+
+        Args:
+            issue_id: Issue ID (internal like '3-41' or readable like 'DEMO-123')
+
+        Returns:
+            Readable project ID (like 'DEMO-41')
+        """
+        try:
+            # If it doesn't look like an internal ID, return as-is
+            if not ("-" in issue_id and issue_id.replace("-", "").isdigit()):
+                return issue_id
+
+            # Fetch the issue to get its readable ID
+            issue = self.client.get(f"issues/{issue_id}?fields=idReadable")
+            return issue.get("idReadable", issue_id)
+        except Exception:
+            # If we can't get the readable ID, return the original
+            return issue_id
+
+    def link_issues(
+        self, source_issue_id: str, target_issue_id: str, link_type: str
+    ) -> dict:
+        """
+        Link two issues together using Commands API.
+
+        Args:
+            source_issue_id: The ID of the source issue
+            target_issue_id: The ID of the target issue
+            link_type: The type of link (e.g., 'Relates', 'Duplicates', 'Depends on')
+
+        Returns:
+            The created link data
+        """
+        # Map link types to correct YouTrack command syntax
+        link_command_map = {
+            "relates": "relates to",
+            "depends on": "depends on",
+            "duplicates": "duplicates",
+            "is duplicated by": "is duplicated by",
+            "is required for": "is required for",
+            "parent for": "parent for",
+            "subtask": "subtask of",
+            "subtask of": "subtask of",
+        }
+
+        # Get internal IDs for both issues (Commands API requires internal IDs in issues array)
+        source_internal_id = self._get_internal_id(source_issue_id)
+        target_internal_id = self._get_internal_id(target_issue_id)
+        
+        # Get readable IDs for command text (Commands API expects readable IDs in command)
+        target_readable_id = self._get_readable_id(target_issue_id)
+
+        # Normalize the link_type to lowercase and map to command
+        link_type_lower = link_type.lower()
+        command_phrase = link_command_map.get(link_type_lower, link_type_lower)
+
+        # Build the command using correct YouTrack syntax with readable target ID
+        # Commands expect readable IDs like "DEMO-37" in command text, but internal IDs in issues array
+        command = f"{command_phrase} {target_readable_id}"
+
+        command_data = {
+            "query": command,
+            "issues": [{"id": source_internal_id}],
+        }
+
+        response = self.client.post("commands", data=command_data)
+
+        # Return success response if the command executed
+        if isinstance(response, dict):
+            return {
+                "status": "success",
+                "message": f"Successfully linked {source_issue_id} to {target_issue_id} with relationship '{link_type}'",
+                "command": command,
+                "source_issue": source_issue_id,
+                "target_issue": target_issue_id,
+                "link_type": link_type,
+                "internal_ids": {
+                    "source": source_internal_id,
+                    "target": target_internal_id,
+                },
+            }
+
+        return response
+
+    def get_issue_links(self, issue_id: str) -> dict:
+        """
+        Get all links for an issue.
+
+        Args:
+            issue_id: The ID of the issue
+
+        Returns:
+            Dictionary containing inward and outward issue links
+        """
+        fields = "id,summary,linkType(name,localizedName),direction"
+        response = self.client.get(f"issues/{issue_id}/links?fields={fields}")
+        return response
+
+    def get_available_link_types(self) -> dict:
+        """
+        Get all available issue link types.
+
+        Returns:
+            List of available link types with their properties
+        """
+        fields = "name,localizedName,sourceToTarget,targetToSource"
+        response = self.client.get(f"issueLinkTypes?fields={fields}")
+        return response
+
+    def _validate_custom_field_value(
+        self, 
+        project_id: str, 
+        field_name: str, 
+        field_value: Any
+    ) -> bool:
+        """
+        Internal method to validate a custom field value.
+
+        Args:
+            project_id: The project ID
+            field_name: The custom field name  
+            field_value: The value to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Get field schema from project
+            field_schema = self._get_custom_field_schema(project_id, field_name)
+            if not field_schema:
+                # If we can't get schema, assume valid (fallback)
+                return True
+            
+            field_type = field_schema.get("type", "")
+            
+            # Type-specific validation
+            if field_type in ["StateMachineBundle", "StateBundle"]:
+                # State field - validate against available states
+                allowed_values = self._get_custom_field_allowed_values(project_id, field_name)
+                return str(field_value) in [str(v) for v in allowed_values]
+            
+            elif field_type in ["EnumBundle", "OwnedBundle"]:
+                # Enum field - validate against enum values
+                allowed_values = self._get_custom_field_allowed_values(project_id, field_name)
+                return str(field_value) in [str(v) for v in allowed_values]
+            
+            elif field_type == "UserBundle":
+                # User field - validate user exists
+                return self._validate_user_exists(field_value)
+            
+            elif field_type == "DateTimeBundle":
+                # Date field - validate format
+                return self._validate_date_format(field_value)
+            
+            elif field_type in ["IntegerBundle", "FloatBundle"]:
+                # Numeric field - validate numeric value
+                return self._validate_numeric_value(field_value, field_type)
+            
+            else:
+                # String or unknown type - minimal validation
+                return field_value is not None
+                
+        except Exception:
+            # If validation fails due to API errors, assume valid (fallback)
+            return True
+
+    def _get_custom_field_schema(self, project_id: str, field_name: str) -> Optional[Dict[str, Any]]:
+        """Get custom field schema from project."""
+        try:
+            fields = self.client.get(f"admin/projects/{project_id}/customFields")
+            for field in fields:
+                if field.get("field", {}).get("name") == field_name:
+                    return field.get("field", {})
+            return None
+        except Exception:
+            return None
+
+    def _get_custom_field_allowed_values(self, project_id: str, field_name: str) -> List[Any]:
+        """Get allowed values for enum/state fields."""
+        try:
+            field_schema = self._get_custom_field_schema(project_id, field_name)
+            if not field_schema:
+                return []
+            
+            field_type = field_schema.get("fieldType", {}).get("valueType")
+            if field_type in ["enum", "state"]:
+                # Get bundle values
+                bundle_id = field_schema.get("fieldType", {}).get("id")
+                if bundle_id:
+                    bundle = self.client.get(f"admin/customFieldSettings/bundles/{field_type}/{bundle_id}")
+                    return [value.get("name", "") for value in bundle.get("values", [])]
+            
+            return []
+        except Exception:
+            return []
+
+    def _validate_user_exists(self, user_value: str) -> bool:
+        """Validate that a user exists."""
+        try:
+            # Try to get user by login or ID
+            self.client.get(f"users/{user_value}")
+            return True
+        except Exception:
+            return False
+
+    def _validate_date_format(self, date_value: Any) -> bool:
+        """Validate date format."""
+        if isinstance(date_value, int):
+            # Unix timestamp
+            return date_value > 0
+        elif isinstance(date_value, str):
+            # ISO date string or other formats
+            import datetime
+            try:
+                datetime.datetime.fromisoformat(date_value.replace('Z', '+00:00'))
+                return True
+            except ValueError:
+                return False
+        return False
+
+    def _validate_numeric_value(self, value: Any, field_type: str) -> bool:
+        """Validate numeric value."""
+        try:
+            if field_type == "IntegerBundle":
+                int(value)
+                return True
+            elif field_type == "FloatBundle":
+                float(value)
+                return True
+        except (ValueError, TypeError):
+            return False
+        return False
+
+    def _format_custom_field_value(self, field_name: str, field_value: Any) -> Dict[str, Any]:
+        """Format custom field value for YouTrack API."""
+        # YouTrack API expects different formats for different field types
+        # The key issue: we need to use field ID, not name, and proper value format
+        
+        if field_value is None:
+            return {
+                "name": field_name,
+                "value": None
+            }
+        
+        # For most string-based fields (State, Enum, etc.)
+        if isinstance(field_value, str):
+            return {
+                "name": field_name,
+                "value": {"name": field_value}
+            }
+        # For user fields, expect login format
+        elif isinstance(field_value, dict) and "login" in field_value:
+            return {
+                "name": field_name,
+                "value": {"login": field_value["login"]}
+            }
+        # For user fields as string (login)
+        elif isinstance(field_value, str) and field_name.lower() in ["assignee", "reporter"]:
+            return {
+                "name": field_name,
+                "value": {"login": field_value}
+            }
+        # For numeric fields (Period, Integer, Float)
+        elif isinstance(field_value, (int, float)):
+            return {
+                "name": field_name,
+                "value": field_value
+            }
+        # For period fields (time tracking)
+        elif isinstance(field_value, str) and field_value.startswith("PT"):
+            return {
+                "name": field_name,
+                "value": {"presentation": field_value}
+            }
+        # For complex objects (already formatted)
+        elif isinstance(field_value, dict):
+            return {
+                "name": field_name,
+                "value": field_value
+            }
+        # Default fallback
+        else:
+            return {
+                "name": field_name,
+                "value": {"name": str(field_value)}
+            }
+
+    def _get_custom_field_id(self, project_id: str, field_name: str) -> Optional[str]:
+        """Get the field ID for a custom field by name."""
+        try:
+            # Use detailed fields query to get complete field information
+            fields_query = "field(id,name,fieldType($type,valueType,id)),canBeEmpty,autoAttached"
+            fields = self.client.get(f"admin/projects/{project_id}/customFields?fields={fields_query}")
+            for field in fields:
+                if field.get("field", {}).get("name") == field_name:
+                    return field.get("field", {}).get("id")
+            return None
+        except Exception as e:
+            logger.warning(f"Error getting field ID for '{field_name}': {str(e)}")
+            return None
+
+    def _get_field_type_info(self, project_id: str, field_id: str) -> Dict[str, Any]:
+        """Get field type information for proper $type formatting."""
+        try:
+            fields_query = "field(id,name,fieldType($type,valueType,id)),canBeEmpty,autoAttached"
+            fields = self.client.get(f"admin/projects/{project_id}/customFields?fields={fields_query}")
+            
+            for field in fields:
+                if field.get("field", {}).get("id") == field_id:
+                    field_type = field.get("field", {}).get("fieldType", {})
+                    return {
+                        "bundle_type": field_type.get("$type", ""),
+                        "value_type": field_type.get("valueType", ""),
+                        "bundle_id": field_type.get("id")
+                    }
+            return {}
+        except Exception as e:
+            logger.warning(f"Error getting field type info for field ID '{field_id}': {str(e)}")
+            return {}
+
+    def _format_custom_field_value_with_id(self, field_id: str, field_value: Any, project_id: str = None) -> Dict[str, Any]:
+        """Format custom field value with field ID for YouTrack API."""
+        # YouTrack API format: Complete IssueCustomField object with proper $type
+        
+        # Get field type information to determine the correct IssueCustomField $type
+        field_type_info = self._get_field_type_info(project_id, field_id) if project_id else {}
+        bundle_type = field_type_info.get("bundle_type", "")
+        value_type = field_type_info.get("value_type", "")
+        
+        # Determine the IssueCustomField $type based on the bundle type and value type
+        issue_field_type = self._get_issue_custom_field_type(bundle_type, value_type, field_id)
+        
+        # Format the value based on type
+        formatted_value = self._format_field_value(field_value, bundle_type, value_type, field_id)
+        
+        return {
+            "id": field_id,
+            "value": formatted_value,
+            "$type": issue_field_type
+        }
+    
+    def _get_issue_custom_field_type(self, bundle_type: str, value_type: str, field_id: str) -> str:
+        """Determine the correct IssueCustomField $type based on field information."""
+        
+        # Check for user fields first (special case)
+        if any(keyword in field_id.lower() for keyword in ["assignee", "reporter", "user"]) or "UserBundle" in bundle_type:
+            return "SingleUserIssueCustomField"
+        
+        # Map based on value type and bundle type
+        if value_type == "enum":
+            return "SingleEnumIssueCustomField"
+        elif value_type == "state":
+            return "StateIssueCustomField"
+        elif value_type == "user":
+            return "SingleUserIssueCustomField"
+        elif value_type == "period":
+            return "PeriodIssueCustomField"
+        elif value_type == "version":
+            return "MultiVersionIssueCustomField"
+        elif value_type in ["integer", "float", "string", "date"]:
+            return "SimpleIssueCustomField"
+        elif value_type == "text":
+            return "TextIssueCustomField"
+        elif "StateBundle" in bundle_type or "StateMachine" in bundle_type:
+            return "StateIssueCustomField"
+        elif "EnumBundle" in bundle_type:
+            return "SingleEnumIssueCustomField"
+        elif "UserBundle" in bundle_type:
+            return "SingleUserIssueCustomField"
+        elif "VersionBundle" in bundle_type:
+            return "MultiVersionIssueCustomField"
+        elif "PeriodBundle" in bundle_type:
+            return "PeriodIssueCustomField"
+        else:
+            # Default fallback based on common field names
+            if "priority" in field_id.lower() or "type" in field_id.lower():
+                return "SingleEnumIssueCustomField"
+            elif "state" in field_id.lower():
+                return "StateIssueCustomField"
+            else:
+                return "SingleEnumIssueCustomField"  # Most common type
+    
+    def _format_field_value(self, field_value: Any, bundle_type: str, value_type: str, field_id: str) -> Any:
+        """Format the field value based on type information."""
+        
+        if field_value is None:
+            return None
+        
+        # For user fields
+        if any(keyword in field_id.lower() for keyword in ["assignee", "reporter", "user"]) or "UserBundle" in bundle_type or value_type == "user":
+            if isinstance(field_value, str):
+                return {
+                    "login": field_value,
+                    "$type": "User"
+                }
+            elif isinstance(field_value, dict) and "login" in field_value:
+                return {
+                    "login": field_value["login"],
+                    "$type": "User"
+                }
+        
+        # For period fields
+        elif value_type == "period" or (isinstance(field_value, str) and field_value.startswith("PT")):
+            return {
+                "presentation": str(field_value),
+                "$type": "PeriodValue"
+            }
+        
+        # For state fields
+        elif value_type == "state" or "StateBundle" in bundle_type or "StateMachine" in bundle_type or "state" in field_id.lower():
+            return {
+                "name": str(field_value),
+                "$type": "StateBundleElement"
+            }
+        
+        # For version/sprint fields
+        elif value_type == "version" or "VersionBundle" in bundle_type:
+            if isinstance(field_value, list):
+                return [{"name": self._normalize_field_value(v), "$type": "VersionBundleElement"} for v in field_value]
+            else:
+                return [{"name": str(field_value), "$type": "VersionBundleElement"}]
+
+        # For enum fields
+        elif value_type == "enum" or "EnumBundle" in bundle_type:
+            return {
+                "name": str(field_value),
+                "$type": "EnumBundleElement"
+            }
+        
+        # For numeric fields
+        elif value_type in ["integer", "float"] and isinstance(field_value, (int, float)):
+            return field_value
+        
+        # For text/string fields
+        elif value_type in ["string", "text"]:
+            return str(field_value)
+        
+        # For date fields
+        elif value_type == "date":
+            return field_value  # Assume it's already properly formatted
+        
+        # Default: treat as enum
+        else:
+            return {
+                "name": str(field_value),
+                "$type": "EnumBundleElement"
+            }
+
+    def _extract_custom_field_value(self, field_value_data: Any) -> Any:
+        """Extract readable value from YouTrack custom field value data."""
+        if not field_value_data:
+            return None
+        
+        if isinstance(field_value_data, dict):
+            # Try different value formats
+            if "name" in field_value_data:
+                return field_value_data["name"]
+            elif "login" in field_value_data:
+                return field_value_data["login"]
+            elif "text" in field_value_data:
+                return field_value_data["text"]
+            elif "id" in field_value_data:
+                return field_value_data["id"]
+        
+        return field_value_data
+
+    def _normalize_field_value(self, field_value: Any) -> str:
+        """
+        Normalize complex field value formats to simple string format.
+        
+        Handles formats like:
+        - Simple: "Task" 
+        - Complex: {"name": "Task"}
+        - Complex: {"$type": "...", "name": "Task"}
+        
+        Args:
+            field_value: The field value in any format
+            
+        Returns:
+            Simple string value
+        """
+        if isinstance(field_value, dict):
+            # Extract name from complex object formats
+            if "name" in field_value:
+                return str(field_value["name"])
+            elif "value" in field_value:
+                # Handle nested value objects
+                nested_value = field_value["value"]
+                if isinstance(nested_value, dict) and "name" in nested_value:
+                    return str(nested_value["name"])
+                else:
+                    return str(nested_value)
+            else:
+                # If no name field, convert entire object to string
+                return str(field_value)
+        else:
+            # Already a simple value
+            return str(field_value)
+
+    def _update_other_custom_fields(self, issue_id: str, custom_fields: Dict[str, Any], validate: bool, use_commands: bool) -> None:
+        """
+        Update non-state custom fields, prioritizing direct field updates.
+        
+        Based on successful testing, uses simple values where possible:
+        - Strings: "Critical", "admin", "Bug"  
+        - NOT complex objects: {"name": "Critical", "id": "123"}
+        
+        Args:
+            issue_id: Issue identifier
+            custom_fields: Dictionary of field names and values
+            validate: Whether to validate field values  
+            use_commands: Whether to try command-based approach as fallback
+        """
+        # Method 1: Direct field update approach (primary method)
+        try:
+            # Always get issue data to extract project ID for schema lookups
+            issue_data = self.get_issue(issue_id)
+            
+            # Validate fields if requested
+            if validate:
+                project_id = None
+                if hasattr(issue_data, 'project') and issue_data.project:
+                    if isinstance(issue_data.project, dict):
+                        project_id = issue_data.project.get('id')
+                    else:
+                        project_id = getattr(issue_data.project, 'id', None)
+                
+                if project_id:
+                    for field_name, field_value in custom_fields.items():
+                        is_valid = self._validate_custom_field_value(project_id, field_name, field_value)
+                        if not is_valid:
+                            raise YouTrackAPIError(f"Custom field validation failed for '{field_name}': '{field_value}' is not a valid value")
+                else:
+                    logger.warning("Could not get project ID for validation, skipping validation")
+            
+            # YouTrack requires proper object types with actual IDs for custom field updates
+            # Try to get project ID for schema lookups (optional for enhanced object creation)
+            project_id = None
+            
+            if hasattr(issue_data, 'project') and issue_data.project:
+                if isinstance(issue_data.project, dict):
+                    project_id = issue_data.project.get('id')
+                else:
+                    project_id = getattr(issue_data.project, 'id', None)
+            
+            # If we can't get project ID, fall back to simple $type approach
+            if not project_id:
+                logger.warning("Could not determine project ID for enhanced object creation, using simple $type approach")
+                use_simple_approach = True
+            else:
+                use_simple_approach = False
+            
+            update_data = {"customFields": []}
+            
+            for field_name, raw_field_value in custom_fields.items():
+                # Normalize complex object formats to simple strings first
+                field_value = self._normalize_field_value(raw_field_value)
+                
+                # Determine field type and construct proper object with actual ID
+                if use_simple_approach:
+                    # Fallback to simple $type approach when project ID is not available
+                    if field_name.lower() in ['state']:
+                        field_type = "StateIssueCustomField"
+                    elif field_name.lower() in ['priority', 'type']:
+                        field_type = "SingleEnumIssueCustomField"
+                    elif field_name.lower() in ['assignee', 'reporter']:
+                        field_type = "SingleUserIssueCustomField"
+                    elif field_name.lower() in ['estimation', 'spent time']:
+                        field_type = "PeriodIssueCustomField"
+                    else:
+                        field_type = "SingleEnumIssueCustomField"
+                    
+                    field_data = {
+                        "$type": field_type,
+                        "name": field_name,
+                        "value": field_value
+                    }
+                else:
+                    # Enhanced approach with proper YouTrack objects and actual IDs
+                    # Handle Estimation with proper PeriodValue format
+                    if field_name.lower() in ['estimation']:
+                        # Estimation REQUIRES PeriodValue format, not simple strings
+                        field_data = self._create_period_field_object(field_name, field_value)
+                    elif field_name.lower() in ['state']:
+                        field_data = self._create_state_field_object(project_id, field_name, field_value)
+                    elif field_name.lower() in ['priority', 'type']:
+                        field_data = self._create_enum_field_object(project_id, field_name, field_value)
+                    elif field_name.lower() in ['assignee', 'reporter']:
+                        field_data = self._create_user_field_object(field_name, field_value)
+                    elif field_name.lower() in ['spent time']:
+                        field_data = self._create_period_field_object(field_name, field_value)
+                    elif field_name.lower() in self._VERSION_FIELD_NAMES:
+                        # Detect version/sprint fields by well-known name
+                        field_data = self._create_version_field_object(project_id, field_name, field_value, multi=True)
+                    else:
+                        # Query the schema to detect version/sprint fields
+                        value_type = self._get_field_value_type(project_id, field_name)
+                        if value_type == "version":
+                            field_data = self._create_version_field_object(project_id, field_name, field_value, multi=True)
+                        else:
+                            # Default to enum for unknown fields
+                            field_data = self._create_enum_field_object(project_id, field_name, field_value)
+                
+                if field_data:
+                    update_data["customFields"].append(field_data)
+            
+            logger.info(f"Updating custom fields for issue {issue_id} using proper YouTrack objects")
+            logger.info(f"Update payload: {json.dumps(update_data, indent=2)}")
+            self.client.post(f"issues/{issue_id}", data=update_data)
+            logger.info(f"Direct field update succeeded for issue {issue_id}")
+            
+        except Exception as direct_error:
+            logger.warning(f"Direct field update failed: {direct_error}")
+            
+            # Method 2: Fallback to command-based approach if enabled
+            if use_commands:
+                logger.info(f"Trying command-based approach as fallback for issue {issue_id}")
+                try:
+                    self._apply_commands_update(issue_id, custom_fields)
+                    logger.info(f"Command-based update succeeded for issue {issue_id}")
+                    return
+                except Exception as cmd_error:
+                    logger.warning(f"Command-based approach also failed: {cmd_error}")
+            
+            # If both direct and command approaches fail, raise the original error with full details
+            error_msg = f"Direct field update failed"
+            if hasattr(direct_error, 'response') and hasattr(direct_error.response, 'json'):
+                try:
+                    error_details = direct_error.response.json()
+                    if 'error_description' in error_details:
+                        error_msg += f": {error_details['error_description']}"
+                    elif 'error' in error_details:
+                        error_msg += f": {error_details['error']}"
+                    else:
+                        error_msg += f": {str(direct_error)}"
+                except:
+                    error_msg += f": {str(direct_error)}"
+            else:
+                error_msg += f": {str(direct_error)}"
+            
+            raise YouTrackAPIError(error_msg)
+
+    def _extract_project_id(self, issue_data) -> str:
+        """Extract project ID from issue data."""
+        if hasattr(issue_data, 'project') and issue_data.project:
+            if isinstance(issue_data.project, dict):
+                return issue_data.project.get('id')
+            else:
+                return getattr(issue_data.project, 'id', None)
+        return None
+
+    def _build_custom_fields_payload(self, custom_fields: Dict[str, Any], project_id: str = None) -> Dict[str, Any]:
+        """Build the custom fields payload with normalized field processing."""
+        update_data = {"customFields": []}
+        use_simple_approach = not project_id
+        
+        if not project_id:
+            logger.warning("Could not determine project ID for enhanced object creation, using simple $type approach")
+        
+        for field_name, raw_field_value in custom_fields.items():
+            # Normalize complex object formats to simple strings first
+            field_value = self._normalize_field_value(raw_field_value)
+            
+            # Create appropriate field object
+            if use_simple_approach:
+                field_data = self._create_simple_field_object(field_name, field_value)
+            else:
+                field_data = self._create_enhanced_field_object(project_id, field_name, field_value)
+            
+            if field_data:
+                update_data["customFields"].append(field_data)
+        
+        return update_data
+
+    def _create_simple_field_object(self, field_name: str, field_value: Any) -> Dict[str, Any]:
+        """Create simple field object using basic $type approach."""
+        field_name_lower = field_name.lower()
+
+        # Known version/sprint multi-value field names
+        version_field_names = self._VERSION_FIELD_NAMES
+
+        if field_name_lower == 'state':
+            field_type = "StateIssueCustomField"
+        elif field_name_lower in ['priority', 'type']:
+            field_type = "SingleEnumIssueCustomField"
+        elif field_name_lower in ['assignee', 'reporter']:
+            field_type = "SingleUserIssueCustomField"
+        elif field_name_lower in ['estimation', 'spent time']:
+            field_type = "PeriodIssueCustomField"
+        elif field_name_lower in version_field_names:
+            # Version/sprint fields require array value
+            if isinstance(field_value, list):
+                value_elements = [{"$type": "VersionBundleElement", "name": self._normalize_field_value(v)} for v in field_value]
+            else:
+                value_elements = [{"$type": "VersionBundleElement", "name": self._normalize_field_value(field_value)}]
+            return {
+                "$type": "MultiVersionIssueCustomField",
+                "name": field_name,
+                "value": value_elements
+            }
+        else:
+            field_type = "SingleEnumIssueCustomField"
+
+        return {
+            "$type": field_type,
+            "name": field_name,
+            "value": field_value
+        }
+
+    def _create_enhanced_field_object(self, project_id: str, field_name: str, field_value: Any) -> Dict[str, Any]:
+        """Create enhanced field object with proper YouTrack objects and actual IDs."""
+        try:
+            field_name_lower = field_name.lower()
+
+            if field_name_lower in ['estimation', 'spent time']:
+                return self._create_period_field_object(field_name, field_value)
+            elif field_name_lower == 'state':
+                return self._create_state_field_object(project_id, field_name, field_value)
+            elif field_name_lower in ['priority', 'type']:
+                return self._create_enum_field_object(project_id, field_name, field_value)
+            elif field_name_lower in ['assignee', 'reporter']:
+                return self._create_user_field_object(field_name, field_value)
+            else:
+                # Query the schema to determine the actual field type
+                value_type = self._get_field_value_type(project_id, field_name)
+                if value_type == "version":
+                    return self._create_version_field_object(project_id, field_name, field_value)
+                else:
+                    # Default to enum for unknown fields
+                    return self._create_enum_field_object(project_id, field_name, field_value)
+        except Exception as e:
+            logger.warning(f"Enhanced field creation failed for '{field_name}': {e}, falling back to simple approach")
+            return self._create_simple_field_object(field_name, field_value)
+
+    def _create_enum_field_object(self, project_id: str, field_name: str, field_value: str) -> Dict[str, Any]:
+        """Create proper EnumBundleElement object with actual ID."""
+        try:
+            # Get allowed values to find the actual ID
+            from youtrack_mcp.api.projects import ProjectsClient
+            projects_client = ProjectsClient(self.client)
+            allowed_values = projects_client.get_custom_field_allowed_values(project_id, field_name)
+            
+            # Find the matching value by name (case-insensitive)
+            value_id = None
+            for value in allowed_values:
+                if value.get('name', '').lower() == field_value.lower():
+                    value_id = value.get('id')
+                    break
+            
+            if value_id:
+                return {
+                    "$type": "SingleEnumIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "EnumBundleElement",
+                        "id": value_id,
+                        "name": field_value
+                    }
+                }
+            else:
+                logger.warning(f"Could not find ID for enum value '{field_value}' in field '{field_name}', trying simple enum object")
+                # Try simple enum object format if ID lookup fails
+                return {
+                    "$type": "SingleEnumIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "EnumBundleElement",
+                        "name": field_value
+                    }
+                }
+        except Exception as e:
+            logger.warning(f"Error creating enum field object for '{field_name}': {e}, trying simple enum object")
+            # Fallback to simple enum object (no ID)
+            return {
+                "$type": "SingleEnumIssueCustomField",
+                "name": field_name,
+                "value": {
+                    "$type": "EnumBundleElement",
+                    "name": field_value
+                }
+            }
+
+    def _create_state_field_object(self, project_id: str, field_name: str, field_value: str) -> Dict[str, Any]:
+        """Create proper StateBundleElement object with actual ID."""
+        try:
+            # Get allowed values to find the actual ID
+            from youtrack_mcp.api.projects import ProjectsClient
+            projects_client = ProjectsClient(self.client)
+            allowed_values = projects_client.get_custom_field_allowed_values(project_id, field_name)
+            
+            # Find the matching state by name (case-insensitive)
+            state_id = None
+            for value in allowed_values:
+                if value.get('name', '').lower() == field_value.lower():
+                    state_id = value.get('id')
+                    break
+            
+            if state_id:
+                return {
+                    "$type": "StateIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "StateBundleElement",
+                        "id": state_id,
+                        "name": field_value
+                    }
+                }
+            else:
+                logger.warning(f"Could not find ID for state value '{field_value}' in field '{field_name}', using simple value")
+                return {
+                    "$type": "StateIssueCustomField",
+                    "name": field_name,
+                    "value": field_value
+                }
+        except Exception as e:
+            logger.warning(f"Error creating state field object for '{field_name}': {e}, using simple value")
+            return {
+                "$type": "StateIssueCustomField",
+                "name": field_name,
+                "value": field_value
+            }
+
+    def _create_user_field_object(self, field_name: str, field_value: str) -> Dict[str, Any]:
+        """Create proper User object with actual ID."""
+        try:
+            # Get user ID by login
+            from youtrack_mcp.api.users import UsersClient
+            users_client = UsersClient(self.client)
+            user_data = users_client.get_user(field_value)
+            
+            if user_data and hasattr(user_data, 'id') and user_data.id:
+                return {
+                    "$type": "SingleUserIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "User",
+                        "id": user_data.id,
+                        "login": field_value
+                    }
+                }
+            else:
+                logger.warning(f"Could not find user ID for login '{field_value}', using simple value")
+                return {
+                    "$type": "SingleUserIssueCustomField",
+                    "name": field_name,
+                    "value": field_value
+                }
+        except Exception as e:
+            logger.warning(f"Error creating user field object for '{field_name}': {e}, using simple value")
+            return {
+                "$type": "SingleUserIssueCustomField",
+                "name": field_name,
+                "value": field_value
+            }
+
+    def _create_period_field_object(self, field_name: str, field_value: str) -> Dict[str, Any]:
+        """Create proper period field object with PeriodValue format."""
+        try:
+            # Convert simple time strings to proper PeriodValue format
+            # Examples: "4h" -> 240 minutes, "30m" -> 30 minutes, "2h 30m" -> 150 minutes
+            
+            minutes = self._parse_time_to_minutes(field_value)
+            
+            if minutes is not None:
+                return {
+                    "$type": "PeriodIssueCustomField",
+                    "name": field_name,
+                    "value": {
+                        "$type": "PeriodValue",
+                        "minutes": minutes
+                    }
+                }
+            else:
+                # Fallback to simple value if parsing fails
+                logger.warning(f"Could not parse period value '{field_value}' for field '{field_name}', using simple value")
+                return {
+                    "$type": "PeriodIssueCustomField",
+                    "name": field_name,
+                    "value": field_value
+                }
+        except Exception as e:
+            logger.warning(f"Error creating period field object for '{field_name}': {e}, using simple value")
+            return {
+                "$type": "PeriodIssueCustomField",
+                "name": field_name,
+                "value": field_value
+            }
+    
+    def _parse_time_to_minutes(self, time_str: str) -> Optional[int]:
+        """Parse time string to minutes for PeriodValue."""
+        try:
+            time_str = time_str.strip().lower()
+            total_minutes = 0
+            
+            # Handle formats like "4h", "30m", "2h 30m", "1h30m"
+            
+            # Extract hours
+            hours_match = re.search(r'(\d+)\s*h', time_str)
+            if hours_match:
+                total_minutes += int(hours_match.group(1)) * 60
+            
+            # Extract minutes
+            minutes_match = re.search(r'(\d+)\s*m', time_str)
+            if minutes_match:
+                total_minutes += int(minutes_match.group(1))
+            
+            # If no h or m found, assume it's just minutes
+            if not hours_match and not minutes_match:
+                # Try to parse as plain number (minutes)
+                if time_str.isdigit():
+                    total_minutes = int(time_str)
+                else:
+                    return None
+            
+            return total_minutes if total_minutes > 0 else None
+            
+        except Exception as e:
+            logger.debug(f"Failed to parse time string '{time_str}': {e}")
+            return None
+
+    def _apply_commands_update(self, issue_id: str, custom_fields: Dict[str, Any]) -> None:
+        """
+        Apply custom field updates using the command-based approach.
+        This method is a fallback and might not be as reliable as direct field updates.
+        """
+        try:
+            command_data = {"query": "updateCustomFields"}
+            for field_name, field_value in custom_fields.items():
+                command_data["query"] += f" {field_name} {field_value}"
+            
+            command_data["issues"] = [{"id": issue_id}]
+            
+            logger.info(f"Applying command-based update for issue {issue_id} with query: {command_data['query']}")
+            self.client.post("commands", data=command_data)
+            logger.info(f"Command-based update succeeded for issue {issue_id}")
+        except Exception as e:
+            logger.warning(f"Command-based update failed: {e}")
+            raise
+
+    def _get_field_value_type(self, project_id: str, field_name: str) -> str:
+        """Get the valueType for a custom field from the project schema."""
+        try:
+            fields_query = "field(id,name,fieldType($type,valueType,id))"
+            fields = self.client.get(f"admin/projects/{project_id}/customFields?fields={fields_query}")
+            for field in fields:
+                if field.get("field", {}).get("name", "").lower() == field_name.lower():
+                    field_type = field.get("field", {}).get("fieldType", {})
+                    return field_type.get("valueType", "")
+            return ""
+        except Exception as e:
+            logger.warning(f"Error getting field value type for '{field_name}': {e}")
+            return ""
+
+    def _create_version_field_object(self, project_id: str, field_name: str, field_value: Any, multi: bool = True) -> Dict[str, Any]:
+        """Create proper VersionBundleElement object for version/sprint fields.
+
+        Args:
+            project_id: Project used to resolve version IDs
+            field_name: The custom field name
+            field_value: A single value or a list of values
+            multi: When True, build a MultiVersionIssueCustomField (list value);
+                   when False, build a SingleVersionIssueCustomField (single value)
+        """
+        def _wrap(value_elements):
+            if multi:
+                return {
+                    "$type": "MultiVersionIssueCustomField",
+                    "name": field_name,
+                    "value": value_elements,
+                }
+            return {
+                "$type": "SingleVersionIssueCustomField",
+                "name": field_name,
+                "value": value_elements[0] if value_elements else None,
+            }
+
+        try:
+            # Accept either a string (single value) or list of values
+            if isinstance(field_value, list):
+                value_names = [self._normalize_field_value(v) for v in field_value]
+            else:
+                value_names = [self._normalize_field_value(field_value)]
+
+            # Try to get version IDs from the project
+            from youtrack_mcp.api.projects import ProjectsClient
+            projects_client = ProjectsClient(self.client)
+            allowed_values = projects_client.get_custom_field_allowed_values(project_id, field_name)
+
+            value_elements = []
+            for name in value_names:
+                element = {"$type": "VersionBundleElement", "name": name}
+                for v in allowed_values:
+                    if v.get('name', '').lower() == name.lower():
+                        element["id"] = v.get('id')
+                        # Prefer the canonical name from the project schema
+                        element["name"] = v.get('name', name)
+                        break
+                value_elements.append(element)
+
+            return _wrap(value_elements)
+        except Exception as e:
+            logger.warning(f"Error creating version field object for '{field_name}': {e}, using minimal format")
+            if isinstance(field_value, list):
+                value_elements = [{"$type": "VersionBundleElement", "name": self._normalize_field_value(v)} for v in field_value]
+            else:
+                value_elements = [{"$type": "VersionBundleElement", "name": self._normalize_field_value(field_value)}]
+            return _wrap(value_elements)
+
+    def get_issue_custom_fields(self, issue_id: str) -> Dict[str, Any]:
+        """
+        Get all custom fields for a specific issue.
+
+        Args:
+            issue_id: The issue ID or readable ID
+
+        Returns:
+            Dictionary of custom field name-value pairs
+        """
+        fields = "customFields(id,name,value($type,name,text,id,login))"
+        response = self.client.get(f"issues/{issue_id}?fields={fields}")
+        
+        custom_fields = {}
+        if "customFields" in response:
+            for field in response["customFields"]:
+                field_name = field.get("name", "")
+                field_value = self._extract_custom_field_value(field.get("value"))
+                custom_fields[field_name] = field_value
+        
+        return custom_fields
+
+    def validate_custom_field_value(
+        self, 
+        project_id: str, 
+        field_name: str, 
+        field_value: Any
+    ) -> Dict[str, Any]:
+        """
+        Validate a custom field value against project schema.
+
+        Args:
+            project_id: The project ID
+            field_name: The custom field name
+            field_value: The value to validate
+
+        Returns:
+            Dictionary with validation result and details
+        """
+        try:
+            is_valid = self._validate_custom_field_value(project_id, field_name, field_value)
+            
+            if is_valid:
+                return {
+                    "valid": True,
+                    "field": field_name,
+                    "value": field_value,
+                    "message": "Valid"
+                }
+            else:
+                # Get available values for better error messages
+                available_values = self._get_custom_field_allowed_values(project_id, field_name)
+                suggestion = f"Available values: {', '.join(map(str, available_values))}" if available_values else "Check field configuration"
+                
+                return {
+                    "valid": False,
+                    "field": field_name,
+                    "value": field_value,
+                    "error": f"Invalid value '{field_value}' for field '{field_name}'",
+                    "suggestion": suggestion
+                }
+        except Exception as e:
+            return {
+                "valid": False,
+                "field": field_name,
+                "value": field_value,
+                "error": f"Validation error: {str(e)}",
+                "suggestion": "Check field name and project configuration"
+            }
+
+    def batch_update_custom_fields(
+        self,
+        updates: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """
+        Update custom fields for multiple issues in a single operation.
+
+        Args:
+            updates: List of update dictionaries with format:
+                    [{"issue_id": "DEMO-123", "fields": {"Priority": "High"}}]
+
+        Returns:
+            List of update results with success/error status
+        """
+        results = []
+        
+        for update in updates:
+            issue_id = update.get("issue_id")
+            fields = update.get("fields", {})
+            
+            if not issue_id:
+                results.append({
+                    "issue_id": None,
+                    "status": "error",
+                    "error": "Missing issue_id in update"
+                })
+                continue
+            
+            if not fields:
+                results.append({
+                    "issue_id": issue_id,
+                    "status": "skipped",
+                    "message": "No fields to update"
+                })
+                continue
+            
+            try:
+                updated_issue = self.update_issue_custom_fields(
+                    issue_id=issue_id,
+                    custom_fields=fields,
+                    validate=update.get("validate", True)
+                )
+                
+                results.append({
+                    "issue_id": issue_id,
+                    "status": "success",
+                    "updated_fields": list(fields.keys()),
+                    "issue_data": updated_issue.model_dump() if hasattr(updated_issue, 'model_dump') else updated_issue
+                })
+                
+            except Exception as e:
+                results.append({
+                    "issue_id": issue_id,
+                    "status": "error",
+                    "error": str(e),
+                    "attempted_fields": list(fields.keys())
+                })
+        
+        return results
+
+    def search_issues(self, query: str, limit: int = 10) -> List[Issue]:
+        """
+        Search for issues using YouTrack query language.
+
+        Args:
+            query: The search query
+            limit: Maximum number of issues to return
+
+        Returns:
+            List of matching issues
+        """
+        # Request additional fields to ensure we get summary
+        fields = "id,idReadable,summary,description,created,updated,project,reporter,assignee,customFields"
+        params = {"query": query, "$top": limit, "fields": fields}
+        response = self.client.get("issues", params=params)
+
+        issues = []
+        if isinstance(response, list):
+            for issue_data in response:
+                try:
+                    issues.append(Issue.model_validate(issue_data))
+                except Exception as e:
+                    logger.warning(f"Error validating issue: {e}")
+                    # Create a basic issue with id
+                    issue_id = issue_data.get(
+                        "id", str(issue_data.get("created", "unknown"))
+                    )
+                    issues.append(
+                        Issue(
+                            id=issue_id,
+                            summary=issue_data.get(
+                                "summary", f"Issue {issue_id}"
+                            ),
+                        )
+                    )
+
+        return issues
+
+    def add_comment(self, issue_id: str, text: str) -> Dict[str, Any]:
+        """
+        Add a comment to an issue.
+
+        Args:
+            issue_id: The issue ID or readable ID
+            text: The comment text
+
+        Returns:
+            The created comment data
+        """
+        data = {"text": text}
+        return self.client.post(f"issues/{issue_id}/comments", data=data)
+
+    def get_attachment_content(
+        self, issue_id: str, attachment_id: str
+    ) -> bytes:
+        """
+        Get the content of an attachment with file size validation.
+
+        Args:
+            issue_id: The issue ID or readable ID
+            attachment_id: The attachment ID
+
+        Returns:
+            The attachment content as bytes
+
+        Raises:
+            ValueError: If attachment not found or file too large
+            YouTrackAPIError: If API request fails
+        """
+        # First, get the attachment metadata to get the URL and size
+        issue_response = self.client.get(
+            f"issues/{issue_id}?fields=attachments(id,url,size,name,mimeType)"
+        )
+
+        # Find the attachment with the matching ID
+        attachment_info = None
+        if "attachments" in issue_response:
+            for attachment in issue_response["attachments"]:
+                if attachment.get("id") == attachment_id:
+                    attachment_info = attachment
+                    break
+
+        if not attachment_info:
+            raise ValueError(
+                f"Attachment {attachment_id} not found in issue {issue_id}"
+            )
+
+        # Check file size limit for base64 encoding
+        # Base64 encoding increases size by ~33%, so for 1MB base64 limit, max original size is ~750KB
+        MAX_ORIGINAL_SIZE = 750 * 1024  # 750KB original file
+        MAX_BASE64_SIZE = (
+            1024 * 1024
+        )  # 1MB after base64 encoding (Claude Desktop limit)
+
+        file_size = attachment_info.get("size", 0)
+        filename = attachment_info.get("name", attachment_id)
+        mime_type = attachment_info.get("mimeType", "unknown")
+
+        if file_size > MAX_ORIGINAL_SIZE:
+            # Calculate what the base64 size would be
+            estimated_base64_size = int(file_size * 1.33)
+            raise ValueError(
+                f"Attachment '{filename}' ({mime_type}) is too large "
+                f"({file_size:,} bytes → ~{estimated_base64_size:,} bytes after base64 encoding). "
+                f"Maximum allowed: {MAX_ORIGINAL_SIZE:,} bytes original (~{MAX_BASE64_SIZE:,} bytes base64)."
+            )
+
+        attachment_url = attachment_info.get("url")
+        if not attachment_url:
+            raise ValueError(
+                f"No download URL found for attachment {attachment_id}"
+            )
+
+        # The URL in the attachment data is relative to the base URL
+        if attachment_url.startswith("/"):
+            attachment_url = attachment_url[1:]  # Remove leading slash
+
+        # Construct the full URL
+        base_url = self.client.base_url
+        if base_url.endswith("/api"):
+            base_url = base_url[:-4]  # Remove '/api' suffix
+
+        full_url = f"{base_url}/{attachment_url}"
+
+        # Make the request to get the attachment content
+        from youtrack_mcp.api.client import YouTrackAPIError
+
+        response = self.client.session.get(full_url)
+
+        # Check for errors
+        if response.status_code >= 400:
+            error_msg = (
+                f"Error getting attachment content: {response.status_code}"
+            )
+            raise YouTrackAPIError(error_msg, response.status_code, response)
+
+        # Double-check the actual content size
+        content_length = len(response.content)
+        if content_length > MAX_ORIGINAL_SIZE:
+            estimated_base64_size = int(content_length * 1.33)
+            raise ValueError(
+                f"Downloaded content size ({content_length:,} bytes → ~{estimated_base64_size:,} bytes base64) "
+                f"exceeds maximum allowed size ({MAX_ORIGINAL_SIZE:,} bytes original). "
+                f"The file may have been modified since metadata was fetched."
+            )
+
+        # Return the binary content
+        return response.content
+
+
+    def _get_internal_id(self, issue_id: str) -> str:
+        """Convert issue ID to internal format if needed."""
+        try:
+            internal_id = self.client.get(f"issues/{issue_id}?fields=id")["id"]
+            return internal_id
+        except Exception:
+            # If that fails, assume the issue_id is already internal
+            return issue_id
+
+    def _get_readable_id(self, issue_id: str) -> str:
+        """
+        Convert an internal issue ID (like 3-37) to readable ID (like DEMO-37).
+        If it's already a readable ID, return as-is.
+
+        Args:
+            issue_id: Issue ID (internal like '3-41' or readable like 'DEMO-123')
+
+        Returns:
+            Readable project ID (like 'DEMO-41')
+        """
+        try:
+            # If it doesn't look like an internal ID, return as-is
+            if not ("-" in issue_id and issue_id.replace("-", "").isdigit()):
+                return issue_id
+
+            # Fetch the issue to get its readable ID
+            issue = self.client.get(f"issues/{issue_id}?fields=idReadable")
+            return issue.get("idReadable", issue_id)
+        except Exception:
+            # If we can't get the readable ID, return the original
+            return issue_id
+
+    def link_issues(
+        self, source_issue_id: str, target_issue_id: str, link_type: str
+    ) -> dict:
+        """
+        Link two issues together using Commands API.
+
+        Args:
+            source_issue_id: The ID of the source issue
+            target_issue_id: The ID of the target issue
+            link_type: The type of link (e.g., 'Relates', 'Duplicates', 'Depends on')
+
+        Returns:
+            The created link data
+        """
+        # Map link types to correct YouTrack command syntax
+        link_command_map = {
+            "relates": "relates to",
+            "depends on": "depends on",
+            "duplicates": "duplicates",
+            "is duplicated by": "is duplicated by",
+            "is required for": "is required for",
+            "parent for": "parent for",
+            "subtask": "subtask of",
+            "subtask of": "subtask of",
+        }
+
+        # Get internal IDs for both issues (Commands API requires internal IDs in issues array)
+        source_internal_id = self._get_internal_id(source_issue_id)
+        target_internal_id = self._get_internal_id(target_issue_id)
+        
+        # Get readable IDs for command text (Commands API expects readable IDs in command)
+        target_readable_id = self._get_readable_id(target_issue_id)
+
+        # Normalize the link_type to lowercase and map to command
+        link_type_lower = link_type.lower()
+        command_phrase = link_command_map.get(link_type_lower, link_type_lower)
+
+        # Build the command using correct YouTrack syntax with readable target ID
+        # Commands expect readable IDs like "DEMO-37" in command text, but internal IDs in issues array
+        command = f"{command_phrase} {target_readable_id}"
+
+        command_data = {
+            "query": command,
+            "issues": [{"id": source_internal_id}],
+        }
+
+        response = self.client.post("commands", data=command_data)
+
+        # Return success response if the command executed
+        if isinstance(response, dict):
+            return {
+                "status": "success",
+                "message": f"Successfully linked {source_issue_id} to {target_issue_id} with relationship '{link_type}'",
+                "command": command,
+                "source_issue": source_issue_id,
+                "target_issue": target_issue_id,
+                "link_type": link_type,
+                "internal_ids": {
+                    "source": source_internal_id,
+                    "target": target_internal_id,
+                },
+            }
+
+        return response
+
+    def get_issue_links(self, issue_id: str) -> dict:
+        """
+        Get all links for an issue.
+
+        Args:
+            issue_id: The ID of the issue
+
+        Returns:
+            Dictionary containing inward and outward issue links
+        """
+        fields = "id,summary,linkType(name,localizedName),direction"
+        response = self.client.get(f"issues/{issue_id}/links?fields={fields}")
+        return response
+
+    def get_available_link_types(self) -> dict:
+        """
+        Get all available issue link types.
+
+        Returns:
+            List of available link types with their properties
+        """
+        fields = "name,localizedName,sourceToTarget,targetToSource"
+        response = self.client.get(f"issueLinkTypes?fields={fields}")
+        return response
+
+    def _validate_custom_field_value(
+        self, 
+        project_id: str, 
+        field_name: str, 
+        field_value: Any
+    ) -> bool:
+        """
+        Internal method to validate a custom field value.
+
+        Args:
+            project_id: The project ID
+            field_name: The custom field name  
+            field_value: The value to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Get field schema from project
+            field_schema = self._get_custom_field_schema(project_id, field_name)
+            if not field_schema:
+                # If we can't get schema, assume valid (fallback)
+                return True
+            
+            field_type = field_schema.get("type", "")
+            
+            # Type-specific validation
+            if field_type in ["StateMachineBundle", "StateBundle"]:
+                # State field - validate against available states
+                allowed_values = self._get_custom_field_allowed_values(project_id, field_name)
+                return str(field_value) in [str(v) for v in allowed_values]
+            
+            elif field_type in ["EnumBundle", "OwnedBundle"]:
+                # Enum field - validate against enum values
+                allowed_values = self._get_custom_field_allowed_values(project_id, field_name)
+                return str(field_value) in [str(v) for v in allowed_values]
+            
+            elif field_type == "UserBundle":
+                # User field - validate user exists
+                return self._validate_user_exists(field_value)
+            
+            elif field_type == "DateTimeBundle":
+                # Date field - validate format
+                return self._validate_date_format(field_value)
+            
+            elif field_type in ["IntegerBundle", "FloatBundle"]:
+                # Numeric field - validate numeric value
+                return self._validate_numeric_value(field_value, field_type)
+            
+            else:
+                # String or unknown type - minimal validation
+                return field_value is not None
+                
+        except Exception:
+            # If validation fails due to API errors, assume valid (fallback)
+            return True
+
+    def _get_custom_field_schema(self, project_id: str, field_name: str) -> Optional[Dict[str, Any]]:
+        """Get custom field schema from project."""
+        try:
+            fields = self.client.get(f"admin/projects/{project_id}/customFields")
+            for field in fields:
+                if field.get("field", {}).get("name") == field_name:
+                    return field.get("field", {})
+            return None
+        except Exception:
+            return None
+
+    def _get_custom_field_allowed_values(self, project_id: str, field_name: str) -> List[Any]:
+        """Get allowed values for enum/state fields."""
+        try:
+            field_schema = self._get_custom_field_schema(project_id, field_name)
+            if not field_schema:
+                return []
+            
+            field_type = field_schema.get("fieldType", {}).get("valueType")
+            if field_type in ["enum", "state"]:
+                # Get bundle values
+                bundle_id = field_schema.get("fieldType", {}).get("id")
+                if bundle_id:
+                    bundle = self.client.get(f"admin/customFieldSettings/bundles/{field_type}/{bundle_id}")
+                    return [value.get("name", "") for value in bundle.get("values", [])]
+            
+            return []
+        except Exception:
+            return []
+
+    def _validate_user_exists(self, user_value: str) -> bool:
+        """Validate that a user exists."""
+        try:
+            # Try to get user by login or ID
+            self.client.get(f"users/{user_value}")
+            return True
+        except Exception:
+            return False
+
+    def _validate_date_format(self, date_value: Any) -> bool:
+        """Validate date format."""
+        if isinstance(date_value, int):
+            # Unix timestamp
+            return date_value > 0
+        elif isinstance(date_value, str):
+            # ISO date string or other formats
+            import datetime
+            try:
+                datetime.datetime.fromisoformat(date_value.replace('Z', '+00:00'))
+                return True
+            except ValueError:
+                return False
+        return False
+
+    def _validate_numeric_value(self, value: Any, field_type: str) -> bool:
+        """Validate numeric value."""
+        try:
+            if field_type == "IntegerBundle":
+                int(value)
+                return True
+            elif field_type == "FloatBundle":
+                float(value)
+                return True
+        except (ValueError, TypeError):
+            return False
+        return False
+
+    def _format_custom_field_value(self, field_name: str, field_value: Any) -> Dict[str, Any]:
+        """Format custom field value for YouTrack API."""
+        # YouTrack API expects different formats for different field types
+        # The key issue: we need to use field ID, not name, and proper value format
+        
+        if field_value is None:
+            return {
+                "name": field_name,
+                "value": None
+            }
+        
+        # For most string-based fields (State, Enum, etc.)
+        if isinstance(field_value, str):
+            return {
+                "name": field_name,
+                "value": {"name": field_value}
+            }
+        # For user fields, expect login format
+        elif isinstance(field_value, dict) and "login" in field_value:
+            return {
+                "name": field_name,
+                "value": {"login": field_value["login"]}
+            }
+        # For user fields as string (login)
+        elif isinstance(field_value, str) and field_name.lower() in ["assignee", "reporter"]:
+            return {
+                "name": field_name,
+                "value": {"login": field_value}
+            }
+        # For numeric fields (Period, Integer, Float)
+        elif isinstance(field_value, (int, float)):
+            return {
+                "name": field_name,
+                "value": field_value
+            }
+        # For period fields (time tracking)
+        elif isinstance(field_value, str) and field_value.startswith("PT"):
+            return {
+                "name": field_name,
+                "value": {"presentation": field_value}
+            }
+        # For complex objects (already formatted)
+        elif isinstance(field_value, dict):
+            return {
+                "name": field_name,
+                "value": field_value
+            }
+        # Default fallback
+        else:
+            return {
+                "name": field_name,
+                "value": {"name": str(field_value)}
+            }
+
+    def _get_custom_field_id(self, project_id: str, field_name: str) -> Optional[str]:
+        """Get the field ID for a custom field by name."""
+        try:
+            # Use detailed fields query to get complete field information
+            fields_query = "field(id,name,fieldType($type,valueType,id)),canBeEmpty,autoAttached"
+            fields = self.client.get(f"admin/projects/{project_id}/customFields?fields={fields_query}")
+            for field in fields:
+                if field.get("field", {}).get("name") == field_name:
+                    return field.get("field", {}).get("id")
+            return None
+        except Exception as e:
+            logger.warning(f"Error getting field ID for '{field_name}': {str(e)}")
+            return None
+
+    def _get_field_type_info(self, project_id: str, field_id: str) -> Dict[str, Any]:
+        """Get field type information for proper $type formatting."""
+        try:
+            fields_query = "field(id,name,fieldType($type,valueType,id)),canBeEmpty,autoAttached"
+            fields = self.client.get(f"admin/projects/{project_id}/customFields?fields={fields_query}")
+            
+            for field in fields:
+                if field.get("field", {}).get("id") == field_id:
+                    field_type = field.get("field", {}).get("fieldType", {})
+                    return {
+                        "bundle_type": field_type.get("$type", ""),
+                        "value_type": field_type.get("valueType", ""),
+                        "bundle_id": field_type.get("id")
+                    }
+            return {}
+        except Exception as e:
+            logger.warning(f"Error getting field type info for field ID '{field_id}': {str(e)}")
+            return {}
+
+    def _format_custom_field_value_with_id(self, field_id: str, field_value: Any, project_id: str = None) -> Dict[str, Any]:
+        """Format custom field value with field ID for YouTrack API."""
+        # YouTrack API format: Complete IssueCustomField object with proper $type
+        
+        # Get field type information to determine the correct IssueCustomField $type
+        field_type_info = self._get_field_type_info(project_id, field_id) if project_id else {}
+        bundle_type = field_type_info.get("bundle_type", "")
+        value_type = field_type_info.get("value_type", "")
+        
+        # Determine the IssueCustomField $type based on the bundle type and value type
+        issue_field_type = self._get_issue_custom_field_type(bundle_type, value_type, field_id)
+        
+        # Format the value based on type
+        formatted_value = self._format_field_value(field_value, bundle_type, value_type, field_id)
+        
+        return {
+            "id": field_id,
+            "value": formatted_value,
+            "$type": issue_field_type
+        }
+    
+    def _get_issue_custom_field_type(self, bundle_type: str, value_type: str, field_id: str) -> str:
+        """Determine the correct IssueCustomField $type based on field information."""
+        
+        # Check for user fields first (special case)
+        if any(keyword in field_id.lower() for keyword in ["assignee", "reporter", "user"]) or "UserBundle" in bundle_type:
+            return "SingleUserIssueCustomField"
+        
+        # Map based on value type and bundle type
+        if value_type == "enum":
+            return "SingleEnumIssueCustomField"
+        elif value_type == "state":
+            return "StateIssueCustomField"
+        elif value_type == "user":
+            return "SingleUserIssueCustomField"
+        elif value_type == "period":
+            return "PeriodIssueCustomField"
+        elif value_type == "version":
+            return "MultiVersionIssueCustomField"
+        elif value_type in ["integer", "float", "string", "date"]:
+            return "SimpleIssueCustomField"
+        elif value_type == "text":
+            return "TextIssueCustomField"
+        elif "StateBundle" in bundle_type or "StateMachine" in bundle_type:
+            return "StateIssueCustomField"
+        elif "EnumBundle" in bundle_type:
+            return "SingleEnumIssueCustomField"
+        elif "UserBundle" in bundle_type:
+            return "SingleUserIssueCustomField"
+        elif "VersionBundle" in bundle_type:
+            return "MultiVersionIssueCustomField"
+        elif "PeriodBundle" in bundle_type:
+            return "PeriodIssueCustomField"
+        else:
+            # Default fallback based on common field names
+            if "priority" in field_id.lower() or "type" in field_id.lower():
+                return "SingleEnumIssueCustomField"
+            elif "state" in field_id.lower():
+                return "StateIssueCustomField"
+            else:
+                return "SingleEnumIssueCustomField"  # Most common type
+    
+    def _format_field_value(self, field_value: Any, bundle_type: str, value_type: str, field_id: str) -> Any:
+        """Format the field value based on type information."""
+        
+        if field_value is None:
+            return None
+        
+        # For user fields
+        if any(keyword in field_id.lower() for keyword in ["assignee", "reporter", "user"]) or "UserBundle" in bundle_type or value_type == "user":
+            if isinstance(field_value, str):
+                return {
+                    "login": field_value,
+                    "$type": "User"
+                }
+            elif isinstance(field_value, dict) and "login" in field_value:
+                return {
+                    "login": field_value["login"],
+                    "$type": "User"
+                }
+        
+        # For period fields
+        elif value_type == "period" or (isinstance(field_value, str) and field_value.startswith("PT")):
+            return {
+                "presentation": str(field_value),
+                "$type": "PeriodValue"
+            }
+        
+        # For state fields
+        elif value_type == "state" or "StateBundle" in bundle_type or "StateMachine" in bundle_type or "state" in field_id.lower():
+            return {
+                "name": str(field_value),
+                "$type": "StateBundleElement"
+            }
+        
+        # For version/sprint fields
+        elif value_type == "version" or "VersionBundle" in bundle_type:
+            if isinstance(field_value, list):
+                return [{"name": self._normalize_field_value(v), "$type": "VersionBundleElement"} for v in field_value]
+            else:
+                return [{"name": str(field_value), "$type": "VersionBundleElement"}]
+
+        # For enum fields
+        elif value_type == "enum" or "EnumBundle" in bundle_type:
+            return {
+                "name": str(field_value),
+                "$type": "EnumBundleElement"
+            }
+        
+        # For numeric fields
+        elif value_type in ["integer", "float"] and isinstance(field_value, (int, float)):
+            return field_value
+        
+        # For text/string fields
+        elif value_type in ["string", "text"]:
+            return str(field_value)
+        
+        # For date fields
+        elif value_type == "date":
+            return field_value  # Assume it's already properly formatted
+        
+        # Default: treat as enum
+        else:
+            return {
+                "name": str(field_value),
+                "$type": "EnumBundleElement"
+            }
+
+    def _extract_custom_field_value(self, field_value_data: Any) -> Any:
+        """Extract readable value from YouTrack custom field value data."""
+        if not field_value_data:
+            return None
+        
+        if isinstance(field_value_data, dict):
+            # Try different value formats
+            if "name" in field_value_data:
+                return field_value_data["name"]
+            elif "login" in field_value_data:
+                return field_value_data["login"]
+            elif "text" in field_value_data:
+                return field_value_data["text"]
+            elif "id" in field_value_data:
+                return field_value_data["id"]
+        
+        return field_value_data
+
+    def _determine_field_type(self, field_name: str, value_type: str, bundle_type: str) -> str:
+        """
+        Determine the correct $type field for YouTrack custom field updates.
+        
+        Args:
+            field_name: Name of the field
+            value_type: Type from schema (enum, state, user, period, etc.)
+            bundle_type: Bundle type from schema
+            
+        Returns:
+            The appropriate $type string for the API
+        """
+        # Map field types to YouTrack $type values
+        type_mapping = {
+            "enum": "SingleEnumIssueCustomField",
+            "state": "StateIssueCustomField", 
+            "user": "SingleUserIssueCustomField",
+            "period": "PeriodIssueCustomField",
+            "ownedField": "SingleOwnedIssueCustomField",  # Subsystem
+            "version": "SingleVersionIssueCustomField",   # Fix/Affected versions
+            "build": "SingleBuildIssueCustomField",       # Fixed in build
+            "string": "SingleStringIssueCustomField",
+            "text": "TextIssueCustomField",
+            "integer": "SingleIntegerIssueCustomField",
+            "float": "SingleFloatIssueCustomField",
+            "date": "SingleDateIssueCustomField",
+            "datetime": "SingleDateTimeIssueCustomField"
+        }
+        
+        # Get the appropriate type, defaulting to enum if not found
+        field_type = type_mapping.get(value_type.lower(), "SingleEnumIssueCustomField")
+        
+        logger.debug(f"Field '{field_name}' (type: {value_type}, bundle: {bundle_type}) mapped to $type: {field_type}")
+        
+        return field_type