MCP JIRA Server

Instructions

Implementation Reference

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

  Registration of the 'search_jira_issues' tool using the @mcp_server.tool decorator with 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)

  The handler function that implements the core logic of the 'search_jira_issues' tool, including calling the helper, performing the actual JIRA search via JiraClient, formatting results, and handling errors.
  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) for the JiraClient.search call.
  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}")