pnd-jira-mcp 1.0.0__py3-none-any.whl

pnd_jira_mcp/client.py

@@ -0,0 +1,792 @@
+"""
+Jira Client Module
+
+Provides integration with Atlassian JIRA REST API v3 and Agile API.
+Self-contained implementation with no external dependencies beyond httpx.
+"""
+
+import json
+import logging
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Any, Optional, Callable
+
+import httpx
+
+logger = logging.getLogger("pnd_jira_mcp.client")
+
+
+@dataclass
+class JiraConfig:
+    """Configuration for JIRA API connection."""
+    base_url: str
+    email: str
+    api_token: str
+    cloud_id: Optional[str] = None
+    
+    field_ai_used: str = "customfield_ai_used"
+    field_agent_name: str = "customfield_agent_name"
+    field_efficiency_score: str = "customfield_ai_efficiency_score"
+    field_duration: str = "customfield_ai_duration"
+    
+    max_retries: int = 3
+    retry_delay_ms: int = 1000
+    timeout_ms: int = 30000
+    
+    debug: bool = False
+    on_request: Optional[Callable[[str, str, Any], None]] = field(default=None, repr=False)
+    on_response: Optional[Callable[[str, str, int, int], None]] = field(default=None, repr=False)
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "JiraConfig":
+        """Create config from dictionary."""
+        return cls(
+            base_url=data.get("base_url", ""),
+            email=data.get("email", ""),
+            api_token=data.get("api_token", ""),
+            cloud_id=data.get("cloud_id"),
+            field_ai_used=data.get("field_ai_used", "customfield_ai_used"),
+            field_agent_name=data.get("field_agent_name", "customfield_agent_name"),
+            field_efficiency_score=data.get("field_efficiency_score", "customfield_ai_efficiency_score"),
+            field_duration=data.get("field_duration", "customfield_ai_duration"),
+            max_retries=data.get("max_retries", 3),
+            retry_delay_ms=data.get("retry_delay_ms", 1000),
+            timeout_ms=data.get("timeout_ms", 30000),
+            debug=data.get("debug", False),
+        )
+    
+    @classmethod
+    def from_env(cls) -> "JiraConfig":
+        """Create config from environment variables."""
+        return cls(
+            base_url=os.environ.get("JIRA_BASE_URL", ""),
+            email=os.environ.get("JIRA_EMAIL", ""),
+            api_token=os.environ.get("JIRA_API_TOKEN", ""),
+            cloud_id=os.environ.get("JIRA_CLOUD_ID"),
+            field_ai_used=os.environ.get("JIRA_FIELD_AI_USED", "customfield_ai_used"),
+            field_agent_name=os.environ.get("JIRA_FIELD_AGENT_NAME", "customfield_agent_name"),
+            field_efficiency_score=os.environ.get("JIRA_FIELD_EFFICIENCY_SCORE", "customfield_ai_efficiency_score"),
+            field_duration=os.environ.get("JIRA_FIELD_DURATION", "customfield_ai_duration"),
+            max_retries=int(os.environ.get("JIRA_MAX_RETRIES", "3")),
+            retry_delay_ms=int(os.environ.get("JIRA_RETRY_DELAY_MS", "1000")),
+            timeout_ms=int(os.environ.get("JIRA_TIMEOUT_MS", "30000")),
+            debug=os.environ.get("JIRA_DEBUG", "").lower() in ("true", "1", "yes"),
+        )
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert config to dictionary (without sensitive data)."""
+        return {
+            "base_url": self.base_url,
+            "email": self.email,
+            "cloud_id": self.cloud_id,
+            "field_ai_used": self.field_ai_used,
+            "field_agent_name": self.field_agent_name,
+            "field_efficiency_score": self.field_efficiency_score,
+            "field_duration": self.field_duration,
+        }
+
+
+@dataclass
+class JiraIssue:
+    """Represents a JIRA issue."""
+    key: str
+    id: str
+    summary: str
+    status: str
+    issue_type: str
+    description: Optional[str] = None
+    assignee: Optional[str] = None
+    priority: Optional[str] = None
+    labels: List[str] = None
+    
+    def __post_init__(self):
+        if self.labels is None:
+            self.labels = []
+    
+    @classmethod
+    def from_api_response(cls, data: Dict[str, Any]) -> "JiraIssue":
+        """Create issue from API response."""
+        fields = data.get("fields", {})
+        return cls(
+            key=data.get("key", ""),
+            id=data.get("id", ""),
+            summary=fields.get("summary", ""),
+            status=fields.get("status", {}).get("name", ""),
+            issue_type=fields.get("issuetype", {}).get("name", ""),
+            description=fields.get("description"),
+            assignee=fields.get("assignee", {}).get("displayName") if fields.get("assignee") else None,
+            priority=fields.get("priority", {}).get("name") if fields.get("priority") else None,
+            labels=fields.get("labels", []),
+        )
+
+
+class JiraClient:
+    """
+    Client for interacting with JIRA REST API v3 and Agile API.
+    
+    Provides methods for:
+    - Adding comments to issues
+    - Updating custom fields
+    - Querying issues
+    - Managing sprints and boards
+    - Managing AI-related metadata
+    """
+    
+    API_VERSION = "3"
+    QAIN_LABEL = "qAIn"
+    
+    def __init__(
+        self,
+        config: Optional[JiraConfig] = None,
+        config_path: Optional[str] = None
+    ):
+        """
+        Initialize the JIRA client.
+        
+        Args:
+            config: JiraConfig object
+            config_path: Path to jira.config.json file
+        """
+        self.config = config or self._load_config(config_path)
+        self._client: Optional[httpx.Client] = None
+        
+        if not self.config.base_url or not self.config.email or not self.config.api_token:
+            logger.warning("JIRA configuration incomplete - some features may not work")
+    
+    def _load_config(self, config_path: Optional[str] = None) -> JiraConfig:
+        """Load configuration from file or environment."""
+        if config_path and os.path.exists(config_path):
+            try:
+                with open(config_path, "r") as f:
+                    data = json.load(f)
+                    if not data.get("api_token"):
+                        data["api_token"] = os.environ.get("JIRA_API_TOKEN", "")
+                    return JiraConfig.from_dict(data)
+            except (json.JSONDecodeError, IOError) as e:
+                logger.warning(f"Failed to load config from {config_path}: {e}")
+        
+        default_path = Path.home() / ".jira" / "config.json"
+        if default_path.exists():
+            try:
+                with open(default_path, "r") as f:
+                    data = json.load(f)
+                    if not data.get("api_token"):
+                        data["api_token"] = os.environ.get("JIRA_API_TOKEN", "")
+                    return JiraConfig.from_dict(data)
+            except (json.JSONDecodeError, IOError) as e:
+                logger.warning(f"Failed to load config from {default_path}: {e}")
+        
+        return JiraConfig.from_env()
+    
+    @property
+    def client(self) -> httpx.Client:
+        """Get or create HTTP client."""
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self._get_api_base_url(),
+                auth=(self.config.email, self.config.api_token),
+                headers={
+                    "Accept": "application/json",
+                    "Content-Type": "application/json",
+                },
+                timeout=self.config.timeout_ms / 1000.0,
+            )
+        return self._client
+    
+    def _get_api_base_url(self) -> str:
+        """Get the API base URL."""
+        base = self.config.base_url.rstrip("/")
+        return f"{base}/rest/api/{self.API_VERSION}/"
+    
+    def _get_agile_base_url(self) -> str:
+        """Get the Agile API base URL."""
+        base = self.config.base_url.rstrip("/")
+        return f"{base}/rest/agile/1.0/"
+    
+    def _calculate_backoff(self, retry_count: int) -> float:
+        """Calculate exponential backoff delay with jitter."""
+        import random
+        base_delay = self.config.retry_delay_ms / 1000.0
+        delay = min(base_delay * (2 ** retry_count) + random.random(), 30.0)
+        return delay
+    
+    def _request_with_retry(
+        self,
+        method: str,
+        endpoint: str,
+        retry_count: int = 0,
+        **kwargs
+    ) -> httpx.Response:
+        """Make HTTP request with retry logic and rate limit handling."""
+        start_time = time.time()
+        url = f"{self._get_api_base_url()}{endpoint}"
+        
+        if self.config.debug:
+            logger.debug(f"[JIRA] {method} {endpoint}")
+        if self.config.on_request:
+            self.config.on_request(method, url, kwargs.get("json"))
+        
+        try:
+            response = getattr(self.client, method.lower())(endpoint, **kwargs)
+            duration_ms = int((time.time() - start_time) * 1000)
+            
+            if self.config.debug:
+                logger.debug(f"[JIRA] {method} {endpoint} -> {response.status_code} ({duration_ms}ms)")
+            if self.config.on_response:
+                self.config.on_response(method, url, response.status_code, duration_ms)
+            
+            if response.status_code == 429:
+                if retry_count < self.config.max_retries:
+                    retry_after = response.headers.get("Retry-After")
+                    if retry_after:
+                        delay = int(retry_after)
+                    else:
+                        delay = self._calculate_backoff(retry_count)
+                    logger.warning(f"Rate limited, retrying in {delay}s...")
+                    time.sleep(delay)
+                    return self._request_with_retry(method, endpoint, retry_count + 1, **kwargs)
+                raise httpx.HTTPStatusError(
+                    f"Rate limit exceeded after {self.config.max_retries} retries",
+                    request=response.request,
+                    response=response
+                )
+            
+            if response.status_code >= 500 and retry_count < self.config.max_retries:
+                delay = self._calculate_backoff(retry_count)
+                logger.warning(f"Server error {response.status_code}, retrying in {delay}s...")
+                time.sleep(delay)
+                return self._request_with_retry(method, endpoint, retry_count + 1, **kwargs)
+            
+            return response
+        except httpx.TimeoutException:
+            if retry_count < self.config.max_retries:
+                delay = self._calculate_backoff(retry_count)
+                logger.warning(f"Request timeout, retrying in {delay}s...")
+                time.sleep(delay)
+                return self._request_with_retry(method, endpoint, retry_count + 1, **kwargs)
+            raise
+        except httpx.RequestError as e:
+            if retry_count < self.config.max_retries:
+                delay = self._calculate_backoff(retry_count)
+                logger.warning(f"Request error: {e}, retrying in {delay}s...")
+                time.sleep(delay)
+                return self._request_with_retry(method, endpoint, retry_count + 1, **kwargs)
+            raise
+    
+    def close(self):
+        """Close the HTTP client."""
+        if self._client:
+            self._client.close()
+            self._client = None
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    def get_issue(self, issue_key: str, fields: Optional[List[str]] = None) -> Optional[JiraIssue]:
+        """Get a JIRA issue by key."""
+        try:
+            params = {}
+            if fields:
+                params["fields"] = ",".join(fields)
+            
+            response = self.client.get(f"issue/{issue_key}", params=params)
+            response.raise_for_status()
+            
+            return JiraIssue.from_api_response(response.json())
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                logger.warning(f"Issue {issue_key} not found")
+                return None
+            logger.error(f"Failed to get issue {issue_key}: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to get issue {issue_key}: {e}")
+            raise
+    
+    def search_issues(
+        self,
+        jql: str,
+        max_results: int = 50,
+        fields: Optional[List[str]] = None
+    ) -> List[JiraIssue]:
+        """Search for issues using JQL."""
+        try:
+            params = {
+                "jql": jql,
+                "maxResults": max_results,
+            }
+            if fields:
+                params["fields"] = ",".join(fields) if isinstance(fields, list) else fields
+            
+            try:
+                response = self._request_with_retry("GET", "search/jql", params=params)
+                response.raise_for_status()
+                data = response.json()
+                return [JiraIssue.from_api_response(issue) for issue in data.get("issues", [])]
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code == 404:
+                    logger.info("Falling back to legacy /search endpoint")
+                    payload = {
+                        "jql": jql,
+                        "maxResults": max_results,
+                    }
+                    if fields:
+                        payload["fields"] = fields
+                    response = self._request_with_retry("POST", "search", json=payload)
+                    response.raise_for_status()
+                    data = response.json()
+                    return [JiraIssue.from_api_response(issue) for issue in data.get("issues", [])]
+                raise
+        except Exception as e:
+            logger.error(f"Failed to search issues: {e}")
+            raise
+
+    def add_label(self, issue_key: str, label: str) -> bool:
+        """Add a label to a JIRA issue if not already present."""
+        try:
+            payload = {
+                "update": {
+                    "labels": [{"add": label}]
+                }
+            }
+            response = self.client.put(f"issue/{issue_key}", json=payload)
+            response.raise_for_status()
+            logger.info(f"Added label '{label}' to {issue_key}")
+            return True
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 400:
+                logger.warning(f"Could not add label to {issue_key}: {e.response.text}")
+                return False
+            logger.error(f"Failed to add label to {issue_key}: {e}")
+            return False
+        except Exception as e:
+            logger.error(f"Failed to add label to {issue_key}: {e}")
+            return False
+
+    def ensure_qain_label(self, issue_key: str) -> bool:
+        """Ensure the qAIn label is present on a JIRA issue."""
+        try:
+            issue = self.get_issue(issue_key, fields=["labels"])
+            if issue and self.QAIN_LABEL in issue.labels:
+                logger.debug(f"qAIn label already exists on {issue_key}")
+                return True
+            return self.add_label(issue_key, self.QAIN_LABEL)
+        except Exception as e:
+            logger.warning(f"Could not ensure qAIn label on {issue_key}: {e}")
+            return False
+
+    def add_comment(
+        self,
+        issue_key: str,
+        body: str,
+        visibility: Optional[Dict[str, str]] = None,
+        add_qain_label: bool = True,
+    ) -> Dict[str, Any]:
+        """Add a comment to a JIRA issue."""
+        try:
+            if add_qain_label:
+                self.ensure_qain_label(issue_key)
+
+            payload = {
+                "body": self._markdown_to_adf(body)
+            }
+
+            if visibility:
+                payload["visibility"] = visibility
+
+            response = self.client.post(f"issue/{issue_key}/comment", json=payload)
+            response.raise_for_status()
+
+            logger.info(f"Added comment to {issue_key} (qAIn label: {add_qain_label})")
+            return response.json()
+        except Exception as e:
+            logger.error(f"Failed to add comment to {issue_key}: {e}")
+            raise
+    
+    def _markdown_to_adf(self, markdown: str) -> Dict[str, Any]:
+        """Convert markdown text to Atlassian Document Format (ADF)."""
+        paragraphs = markdown.strip().split("\n\n")
+        content = []
+        
+        for para in paragraphs:
+            lines = para.split("\n")
+            
+            heading_match = re.match(r'^(#{1,6})\s+(.+)$', lines[0]) if lines else None
+            if heading_match and len(lines) == 1:
+                level = len(heading_match.group(1))
+                content.append({
+                    "type": "heading",
+                    "attrs": {"level": level},
+                    "content": self._parse_inline_formatting(heading_match.group(2))
+                })
+                continue
+            
+            if lines[0].startswith("```"):
+                language = lines[0][3:].strip() or None
+                code_lines = []
+                i = 1
+                while i < len(lines) and not lines[i].startswith("```"):
+                    code_lines.append(lines[i])
+                    i += 1
+                code_block: Dict[str, Any] = {
+                    "type": "codeBlock",
+                    "content": [{"type": "text", "text": "\n".join(code_lines)}]
+                }
+                if language:
+                    code_block["attrs"] = {"language": language}
+                content.append(code_block)
+                continue
+            
+            if all(line.strip().startswith("- ") for line in lines if line.strip()):
+                list_items = []
+                for line in lines:
+                    if line.strip().startswith("- "):
+                        text = line.strip()[2:]
+                        list_items.append({
+                            "type": "listItem",
+                            "content": [{
+                                "type": "paragraph",
+                                "content": self._parse_inline_formatting(text)
+                            }]
+                        })
+                if list_items:
+                    content.append({
+                        "type": "bulletList",
+                        "content": list_items
+                    })
+                continue
+            
+            if all(re.match(r'^\d+\.\s+', line.strip()) for line in lines if line.strip()):
+                list_items = []
+                for line in lines:
+                    match = re.match(r'^\d+\.\s+(.+)$', line.strip())
+                    if match:
+                        list_items.append({
+                            "type": "listItem",
+                            "content": [{
+                                "type": "paragraph",
+                                "content": self._parse_inline_formatting(match.group(1))
+                            }]
+                        })
+                if list_items:
+                    content.append({
+                        "type": "orderedList",
+                        "content": list_items
+                    })
+                continue
+            
+            if all(line.startswith(">") or not line.strip() for line in lines):
+                quote_content = []
+                for line in lines:
+                    if line.strip():
+                        quote_text = re.sub(r'^>\s?', '', line)
+                        quote_content.append({
+                            "type": "paragraph",
+                            "content": self._parse_inline_formatting(quote_text)
+                        })
+                if quote_content:
+                    content.append({
+                        "type": "blockquote",
+                        "content": quote_content
+                    })
+                continue
+            
+            text_content: List[Dict[str, Any]] = []
+            for line in lines:
+                if text_content:
+                    text_content.append({"type": "hardBreak"})
+                text_content.extend(self._parse_inline_formatting(line))
+            
+            if text_content:
+                content.append({
+                    "type": "paragraph",
+                    "content": text_content
+                })
+        
+        return {
+            "type": "doc",
+            "version": 1,
+            "content": content
+        }
+    
+    def _parse_inline_formatting(self, text: str) -> List[Dict[str, Any]]:
+        """Parse inline markdown formatting (bold, italic, links, strikethrough, code)."""
+        nodes: List[Dict[str, Any]] = []
+        remaining = text
+        
+        while remaining:
+            link_match = re.match(r'\[([^\]]+)\]\(([^)]+)\)', remaining)
+            if link_match:
+                nodes.append({
+                    "type": "text",
+                    "text": link_match.group(1),
+                    "marks": [{"type": "link", "attrs": {"href": link_match.group(2)}}]
+                })
+                remaining = remaining[len(link_match.group(0)):]
+                continue
+            
+            bold_match = re.match(r'\*\*(.+?)\*\*', remaining)
+            if bold_match:
+                nodes.append({
+                    "type": "text",
+                    "text": bold_match.group(1),
+                    "marks": [{"type": "strong"}]
+                })
+                remaining = remaining[len(bold_match.group(0)):]
+                continue
+            
+            italic_match = re.match(r'\*(.+?)\*', remaining)
+            if italic_match:
+                nodes.append({
+                    "type": "text",
+                    "text": italic_match.group(1),
+                    "marks": [{"type": "em"}]
+                })
+                remaining = remaining[len(italic_match.group(0)):]
+                continue
+            
+            strike_match = re.match(r'~~(.+?)~~', remaining)
+            if strike_match:
+                nodes.append({
+                    "type": "text",
+                    "text": strike_match.group(1),
+                    "marks": [{"type": "strike"}]
+                })
+                remaining = remaining[len(strike_match.group(0)):]
+                continue
+            
+            code_match = re.match(r'`([^`]+)`', remaining)
+            if code_match:
+                nodes.append({
+                    "type": "text",
+                    "text": code_match.group(1),
+                    "marks": [{"type": "code"}]
+                })
+                remaining = remaining[len(code_match.group(0)):]
+                continue
+            
+            next_special = len(remaining)
+            for pattern in [r'\[', r'\*\*', r'\*', r'~~', r'`']:
+                match = re.search(pattern, remaining[1:])
+                if match:
+                    next_special = min(next_special, match.start() + 1)
+            
+            if next_special > 0:
+                nodes.append({"type": "text", "text": remaining[:next_special]})
+                remaining = remaining[next_special:]
+            else:
+                nodes.append({"type": "text", "text": remaining})
+                break
+        
+        return nodes if nodes else [{"type": "text", "text": ""}]
+
+    def update_fields(self, issue_key: str, fields: Dict[str, Any]) -> bool:
+        """Update fields on a JIRA issue."""
+        try:
+            payload = {"fields": fields}
+            response = self.client.put(f"issue/{issue_key}", json=payload)
+            response.raise_for_status()
+            logger.info(f"Updated fields on {issue_key}")
+            return True
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 400:
+                logger.warning(f"Failed to update fields on {issue_key}: {e.response.text}")
+                return False
+            raise
+        except Exception as e:
+            logger.error(f"Failed to update fields on {issue_key}: {e}")
+            raise
+    
+    def update_ai_fields(
+        self,
+        issue_key: str,
+        ai_used: bool = True,
+        agent_name: Optional[str] = None,
+        efficiency_score: Optional[float] = None,
+        duration_ms: Optional[float] = None
+    ) -> bool:
+        """Update AI-related custom fields on a JIRA issue."""
+        fields: Dict[str, Any] = {}
+        
+        if self.config.field_ai_used:
+            fields[self.config.field_ai_used] = ai_used
+        
+        if agent_name and self.config.field_agent_name:
+            fields[self.config.field_agent_name] = agent_name
+        
+        if efficiency_score is not None and self.config.field_efficiency_score:
+            fields[self.config.field_efficiency_score] = efficiency_score
+        
+        if duration_ms is not None and self.config.field_duration:
+            fields[self.config.field_duration] = duration_ms / 1000
+        
+        if not fields:
+            logger.warning("No AI fields configured to update")
+            return False
+        
+        return self.update_fields(issue_key, fields)
+
+    def get_transitions(self, issue_key: str) -> List[Dict[str, Any]]:
+        """Get available transitions for an issue."""
+        try:
+            response = self.client.get(f"issue/{issue_key}/transitions")
+            response.raise_for_status()
+            return response.json().get("transitions", [])
+        except Exception as e:
+            logger.error(f"Failed to get transitions for {issue_key}: {e}")
+            raise
+    
+    def transition_issue(
+        self,
+        issue_key: str,
+        transition_id: str,
+        fields: Optional[Dict[str, Any]] = None,
+        comment: Optional[str] = None
+    ) -> bool:
+        """Transition an issue to a new status."""
+        try:
+            payload: Dict[str, Any] = {
+                "transition": {"id": transition_id}
+            }
+            
+            if fields:
+                payload["fields"] = fields
+            
+            if comment:
+                payload["update"] = {
+                    "comment": [{
+                        "add": {"body": self._markdown_to_adf(comment)}
+                    }]
+                }
+            
+            response = self.client.post(f"issue/{issue_key}/transitions", json=payload)
+            response.raise_for_status()
+            
+            logger.info(f"Transitioned {issue_key}")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to transition {issue_key}: {e}")
+            raise
+
+    def test_connection(self) -> bool:
+        """Test the JIRA connection."""
+        try:
+            response = self.client.get("myself")
+            response.raise_for_status()
+            user = response.json()
+            logger.info(f"Connected to JIRA as {user.get('displayName', 'Unknown')}")
+            return True
+        except Exception as e:
+            logger.error(f"JIRA connection test failed: {e}")
+            return False
+
+    def get_boards(self, project_key: Optional[str] = None, board_type: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Get all boards, optionally filtered by project or type."""
+        try:
+            params: Dict[str, Any] = {"maxResults": 100}
+            if project_key:
+                params["projectKeyOrId"] = project_key
+            if board_type:
+                params["type"] = board_type
+            
+            url = f"{self._get_agile_base_url()}board"
+            response = httpx.get(
+                url,
+                params=params,
+                auth=(self.config.email, self.config.api_token),
+                headers={"Accept": "application/json"},
+                timeout=self.config.timeout_ms / 1000.0,
+            )
+            response.raise_for_status()
+            return response.json().get("values", [])
+        except Exception as e:
+            logger.error(f"Failed to get boards: {e}")
+            raise
+
+    def get_sprints(
+        self,
+        board_id: int,
+        state: Optional[str] = None,
+        max_results: int = 50
+    ) -> List[Dict[str, Any]]:
+        """Get sprints for a board."""
+        try:
+            params: Dict[str, Any] = {"maxResults": max_results}
+            if state:
+                params["state"] = state
+            
+            url = f"{self._get_agile_base_url()}board/{board_id}/sprint"
+            response = httpx.get(
+                url,
+                params=params,
+                auth=(self.config.email, self.config.api_token),
+                headers={"Accept": "application/json"},
+                timeout=self.config.timeout_ms / 1000.0,
+            )
+            response.raise_for_status()
+            return response.json().get("values", [])
+        except Exception as e:
+            logger.error(f"Failed to get sprints for board {board_id}: {e}")
+            raise
+
+    def get_sprint(self, sprint_id: int) -> Optional[Dict[str, Any]]:
+        """Get sprint details by ID."""
+        try:
+            url = f"{self._get_agile_base_url()}sprint/{sprint_id}"
+            response = httpx.get(
+                url,
+                auth=(self.config.email, self.config.api_token),
+                headers={"Accept": "application/json"},
+                timeout=self.config.timeout_ms / 1000.0,
+            )
+            response.raise_for_status()
+            return response.json()
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return None
+            raise
+        except Exception as e:
+            logger.error(f"Failed to get sprint {sprint_id}: {e}")
+            raise
+
+    def get_active_sprint(self, board_id: int) -> Optional[Dict[str, Any]]:
+        """Get the active sprint for a board."""
+        try:
+            sprints = self.get_sprints(board_id, state="active")
+            return sprints[0] if sprints else None
+        except Exception as e:
+            logger.error(f"Failed to get active sprint for board {board_id}: {e}")
+            raise
+
+    def get_sprint_issues(
+        self,
+        sprint_id: int,
+        fields: Optional[List[str]] = None,
+        max_results: int = 200
+    ) -> List[JiraIssue]:
+        """Get all issues in a sprint."""
+        try:
+            params: Dict[str, Any] = {"maxResults": max_results}
+            if fields:
+                params["fields"] = ",".join(fields)
+            
+            url = f"{self._get_agile_base_url()}sprint/{sprint_id}/issue"
+            response = httpx.get(
+                url,
+                params=params,
+                auth=(self.config.email, self.config.api_token),
+                headers={"Accept": "application/json"},
+                timeout=self.config.timeout_ms / 1000.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+            return [JiraIssue.from_api_response(issue) for issue in data.get("issues", [])]
+        except Exception as e:
+            logger.error(f"Failed to get issues for sprint {sprint_id}: {e}")
+            raise