Jira MCP Server

Instructions

Implementation Reference

• src/mcp_server_jira/server.py:415-474 (handler)

  Primary tool handler: performs paginated JQL search using JiraV3APIClient, respects max_results limit, returns raw API issue data.

  async def search_jira_issues(
      self, jql: str, max_results: int = 10
  ) -> List[JiraIssueResult]:
      """Search for issues using JQL via v3 REST API with pagination support"""
      logger.info("Starting search_jira_issues...")
  
      try:
          # Use v3 API client
          v3_client = self._get_v3_api_client()
          
          # Collect all issues from all pages
          all_issues = []
          start_at = 0
          page_size = min(max_results, 100)  # Jira typically limits to 100 per page
          
          while True:
              logger.debug(f"Fetching page starting at {start_at} with page size {page_size}")
              response_data = await v3_client.search_issues(
                  jql=jql, 
                  start_at=start_at,
                  max_results=page_size
              )
  
              # Extract issues from current page
              page_issues = response_data.get("issues", [])
              all_issues.extend(page_issues)
              
              logger.debug(f"Retrieved {len(page_issues)} issues from current page. Total so far: {len(all_issues)}")
  
              # Check if we've reached the user's max_results limit
              if len(all_issues) >= max_results:
                  # Trim to exact max_results if we exceeded it
                  all_issues = all_issues[:max_results]
                  logger.debug(f"Reached max_results limit of {max_results}, stopping pagination")
                  break
  
              # Check if this is the last page according to API
              is_last = response_data.get("isLast", True)
              if is_last:
                  logger.debug("API indicates this is the last page, stopping pagination")
                  break
  
              # If we have more pages, prepare for next iteration
              start_at = len(all_issues)  # Use actual number of issues retrieved so far
              
              # Adjust page size for next request to not exceed max_results
              remaining_needed = max_results - len(all_issues)
              page_size = min(remaining_needed, 100)
  
          # Return raw issues list for full JSON data
          logger.info(f"Returning raw issues ({len(all_issues)}) for JQL: {jql}")
          return all_issues
  
  
      except Exception as e:
          error_msg = f"Failed to search issues: {type(e).__name__}: {str(e)}"
          logger.error(error_msg, exc_info=True)
          print(error_msg)
          raise ValueError(error_msg)

• src/mcp_server_jira/server.py:1199-1216 (registration)

  Tool registration including name, description, and input schema definition.

  Tool(
      name=JiraTools.SEARCH_ISSUES.value,
      description="Search for Jira issues using JQL (Jira Query Language)",
      inputSchema={
          "type": "object",
          "properties": {
              "jql": {
                  "type": "string",
                  "description": "JQL query string (e.g., 'project = MYPROJ AND status = \"In Progress\"')",
              },
              "max_results": {
                  "type": "integer",
                  "description": "Maximum number of results to return (default: 10)",
              },
          },
          "required": ["jql"],
      },
  ),

• src/mcp_server_jira/server.py:1426-1434 (handler)

  Tool dispatcher case in call_tool() that extracts arguments and invokes the search_jira_issues handler.

  case JiraTools.SEARCH_ISSUES.value:
      logger.info("Calling async tool search_jira_issues...")
      jql = arguments.get("jql")
      if not jql:
          raise ValueError("Missing required argument: jql")
      max_results = arguments.get("max_results", 10)
      result = await jira_server.search_jira_issues(jql, max_results)
      logger.info("Async tool search_jira_issues completed.")

• src/mcp_server_jira/jira_v3_api.py:527-601 (helper)

  Low-level helper: makes HTTP request to Jira v3 /search/jql endpoint with JQL and pagination params.

  async def search_issues(
      self,
      jql: str,
      start_at: int = 0,
      max_results: int = 50,
      fields: Optional[str] = None,
      expand: Optional[str] = None,
      properties: Optional[list] = None,
      fields_by_keys: Optional[bool] = None,
      fail_fast: Optional[bool] = None,
      reconcile_issues: Optional[list] = None,
  ) -> Dict[str, Any]:
      """
      Search for issues using JQL enhanced search (GET) via v3 REST API.
      
      Searches for issues using JQL. Recent updates might not be immediately visible 
      in the returned search results. If you need read-after-write consistency, 
      you can utilize the reconcileIssues parameter to ensure stronger consistency assurances. 
      This operation can be accessed anonymously.
  
      Args:
          jql: JQL query string
          start_at: Index of the first issue to return (default: 0)
          max_results: Maximum number of results to return (default: 50)
          fields: Comma-separated list of fields to include in response
          expand: Use expand to include additional information about issues
          properties: List of issue properties to include in response
          fields_by_keys: Reference fields by their key (rather than ID)
          fail_fast: Fail fast when JQL query validation fails
          reconcile_issues: List of issue IDs to reconcile for read-after-write consistency
  
      Returns:
          Dictionary containing search results with:
          - issues: List of issue dictionaries
          - isLast: Boolean indicating if this is the last page
          - startAt: Starting index of results
          - maxResults: Maximum results per page
          - total: Total number of issues matching the query
  
      Raises:
          ValueError: If the API request fails or JQL is invalid
      """
      if not jql:
          raise ValueError("jql parameter is required")
  
      # Build query parameters
      params = {
          "jql": jql,
          "startAt": start_at,
          "maxResults": max_results,
      }
  
      # Add optional parameters if provided
      params["fields"] = fields if fields is not None else "*all"
      if expand:
          params["expand"] = expand
      if properties:
          params["properties"] = properties
      if fields_by_keys is not None:
          params["fieldsByKeys"] = fields_by_keys
      if fail_fast is not None:
          params["failFast"] = fail_fast
      if reconcile_issues:
          params["reconcileIssues"] = reconcile_issues
  
      # Remove None values
      params = {k: v for k, v in params.items() if v is not None}
  
      endpoint = "/search/jql"
      logger.debug(f"Searching issues with v3 API endpoint: {endpoint}")
      logger.debug(f"Search params: {params}")
      
      response_data = await self._make_v3_api_request("GET", endpoint, params=params)
      logger.debug(f"Search issues API response: {json.dumps(response_data, indent=2)}")
      return response_data

• src/mcp_server_jira/server.py:76-94 (schema)

  Pydantic model intended for issue results (though handler returns raw dicts).

  class JiraIssueResult(BaseModel):
      key: str
      summary: str
      description: Optional[str] = None
      status: Optional[str] = None
      assignee: Optional[str] = None
      reporter: Optional[str] = None
      created: Optional[str] = None
      updated: Optional[str] = None
      fields: Optional[Dict[str, Any]] = None
      comments: Optional[List[Dict[str, Any]]] = None
      watchers: Optional[Dict[str, Any]] = None
      attachments: Optional[List[Dict[str, Any]]] = None
      subtasks: Optional[List[Dict[str, Any]]] = None
      project: Optional[Dict[str, Any]] = None
      issue_links: Optional[List[Dict[str, Any]]] = None
      worklog: Optional[List[Dict[str, Any]]] = None
      timetracking: Optional[Dict[str, Any]] = None