MCP JIRA Server

Instructions

Implementation Reference

• mcp_jira/server/app.py:187-190 (registration)

  Registration of the MCP tool 'search_jira_issues' using the @mcp_server.tool decorator, specifying name and description.

  @mcp_server.tool(
      name="search_jira_issues",
      description="Search for Jira issues using JQL (Jira Query Language) syntax",
  )

• mcp_jira/server/app.py:191-322 (handler)

  Main handler function for the 'search_jira_issues' tool. Prepares search parameters, instantiates JiraClient based on site config, performs the search, formats the results (basic or detailed view), and returns formatted text content. Handles errors gracefully.

  def search_jira_issues_tool(
      query: str,
      site_alias: str = None,
      basic_only: bool = False
  ) -> types.TextContent:
      """
      Search for JIRA issues using JQL syntax.
      
      Args:
          query: JQL query string (e.g., "project = ABC AND status = 'In Progress'")
          site_alias: Optional site alias for multi-site configurations
          basic_only: If True, return only key, summary, and description for each issue (default: False)
      """
      logger.debug(
          f"search_jira_issues_tool received: query='{query}', site_alias={site_alias}, basic_only={basic_only}"
      )
      try:
          # 1. Get the prepared search data (using default max_results)
          search_data = jira_tools.search_jira_issues_implementation(
              query=query,
              site_alias=site_alias,
              max_results=50,  # Default value similar to conduit
              basic_only=basic_only
          )
          logger.debug(f"Search data prepared by implementation: {search_data}")
  
          # 2. Get active JIRA site configuration
          active_site_config_dict = get_active_jira_config(alias=site_alias, server_config=config)
          logger.debug(f"Using JIRA site config for alias '{site_alias}'")
  
          # 3. Instantiate JiraClient with the specific site config
          jira_client = JiraClient(site_config=active_site_config_dict)
          logger.debug("JiraClient instantiated.")
  
          # 4. Call the JiraClient to search for issues
          search_results = jira_client.search(
              jql_query=search_data["jql_query"],
              max_results=search_data["max_results"],
              basic_only=search_data["basic_only"]
          )
          logger.info(f"JIRA search found {len(search_results)} issues")
  
          # Format results based on basic_only mode
          if not search_results:
              response_text = f"No issues found for query: {query}"
          else:
              formatted_results = []
              for issue in search_results:
                  if search_data["basic_only"]:
                      # Basic mode: show only key, summary, and description
                      issue_lines = [
                          f"**{issue['key']}**: {issue['summary']}"
                      ]
                      
                      # Include description if available
                      if issue.get('description'):
                          issue_lines.append(f"  - **Description**: {issue['description']}")
                  else:
                      # Full mode: show all available information
                      issue_lines = [
                          f"**{issue['key']}**: {issue['summary']}",
                          f"  - **Project**: {issue['project'] or 'N/A'}",
                          f"  - **Type**: {issue['issue_type'] or 'N/A'}",
                          f"  - **Status**: {issue['status'] or 'N/A'}",
                          f"  - **Priority**: {issue['priority'] or 'N/A'}",
                          f"  - **Assignee**: {issue['assignee'] or 'Unassigned'}",
                          f"  - **Created**: {issue['created'] or 'N/A'}",
                          f"  - **Updated**: {issue['updated'] or 'N/A'}",
                          f"  - **URL**: {issue['url']}"
                      ]
                      
                      # Include description if available
                      if issue.get('description'):
                          issue_lines.append(f"  - **Description**: {issue['description']}")
                      
                      # Include issue links (links to other JIRA issues)
                      if issue.get('issue_links'):
                          issue_lines.append(f"  - **Issue Links**:")
                          for link in issue['issue_links']:
                              if link.get('direction') == 'inward':
                                  issue_lines.append(f"    - {link['inward']}: {link['issue_key']} - {link['issue_summary']} ({link['issue_status']})")
                              else:
                                  issue_lines.append(f"    - {link['outward']}: {link['issue_key']} - {link['issue_summary']} ({link['issue_status']})")
                      
                      # Include remote links if available
                      if issue.get('remote_links'):
                          issue_lines.append(f"  - **Remote Links**:")
                          for link in issue['remote_links']:
                              if link.get('url') and link.get('title'):
                                  issue_lines.append(f"    - [{link['title']}]({link['url']})")
                      
                      # Include comments if available
                      if issue.get('comments'):
                          issue_lines.append(f"  - **Comments** ({len(issue['comments'])} total):")
                          # Show first 3 comments to avoid too much output
                          for comment in issue['comments'][:3]:
                              issue_lines.append(f"    - **{comment['author']}** ({comment['created']}):")
                              # Truncate long comments
                              body = comment['body'][:200] + "..." if len(comment['body']) > 200 else comment['body']
                              issue_lines.append(f"      {body}")
                          if len(issue['comments']) > 3:
                              issue_lines.append(f"    - ... and {len(issue['comments']) - 3} more comments")
                      
                      # Include worklogs if available
                      if issue.get('worklogs'):
                          total_seconds = sum(w.get('timeSpentSeconds', 0) for w in issue['worklogs'])
                          total_hours = total_seconds / 3600
                          issue_lines.append(f"  - **Worklogs** ({len(issue['worklogs'])} entries, {total_hours:.1f} hours total)")
                  
                  formatted_results.append("\n".join(issue_lines))
              
              response_text = f"Found {len(search_results)} issues:\n\n" + "\n\n".join(formatted_results)
  
          return types.TextContent(
              type="text",
              text=response_text,
              format="text/plain"
          )
      except JiraServiceError as e:
          logger.error(f"JiraServiceError in search_jira_issues_tool: {e}", exc_info=True)
          return types.TextContent(
              type="text",
              text=f"Error searching JIRA issues: {e}",
              format="text/plain"
          )
      except Exception as e:
          logger.error(f"Unexpected error in search_jira_issues_tool: {e}", exc_info=True)
          return types.TextContent(
              type="text",
              text=f"An unexpected error occurred: {e}",
              format="text/plain"
          )

• mcp_jira/tools/jira_tools.py:123-158 (helper)

  Helper function that prepares the search parameters (JQL query, max_results, basic_only) as a dictionary for use by the JiraClient.search method. Does not perform the actual search.

  def search_jira_issues_implementation(
      query: str,
      site_alias: Optional[str] = None,
      max_results: int = 50,
      basic_only: bool = False
  ) -> Dict[str, Any]:
      """
      Implementation for searching JIRA issues using JQL.
      Returns the query and parameters for the JiraClient.search call.
      The site_alias is used by the calling layer for configuration resolution.
      
      Args:
          query: JQL query string
          site_alias: Optional site alias for multi-site configurations
          max_results: Maximum number of results to return (default: 50)
          basic_only: If True, return only key, summary, and description for each issue (default: False)
      """
      try:
          # Prepare search parameters for the client
          search_data = {
              "jql_query": query,
              "max_results": max_results,
              "basic_only": basic_only
          }
          
          # Note: site_alias is used by the MCP server layer for configuration resolution
          # and doesn't need to be included in the returned data
          
          return search_data
  
      except JiraServiceError as e:
          # Re-raise JiraServiceError to be handled by the MCP framework
          raise
      except Exception as e:
          # Catch any other unexpected errors and wrap them in JiraServiceError
          raise JiraServiceError(f"Unexpected error occurred in search_jira_issues_implementation: {e}")