Personal JIRA MCP

Instructions

Implementation Reference

• src/jira_mcp/server.py:717-769 (handler)

  The main handler and registration for the get_issue_attachments MCP tool. Lists all attachments for a JIRA issue, checks local existence, and optionally downloads via download_all_attachments.

  @mcp.tool(
      description="获取JIRA问题的所有附件",
  )
  def get_issue_attachments(
      issue_key: str,
      download: bool = False
  ) -> Dict[str, Any]:
      """获取JIRA问题的所有附件信息.
      
      Args:
          issue_key: JIRA问题键
          download: 是否下载附件到本地
      
      Returns:
          Dict[str, Any]: 附件列表
      """
      logger.info(f"获取问题附件列表: {issue_key}, download={download}")
      
      if download:
          return download_all_attachments(issue_key)
      
      try:
          client = get_jira_client()
          issue = client.issue(issue_key)
          
          attachments = []
          if hasattr(issue.fields, "attachment") and issue.fields.attachment:
              for attachment in issue.fields.attachment:
                  # 检查附件是否已存在于本地
                  local_path = get_attachment_path(issue_key, attachment.filename)
                  exists_locally = os.path.exists(local_path)
                  
                  attachments.append({
                      "id": attachment.id,
                      "filename": attachment.filename,
                      "size": attachment.size,
                      "content_type": attachment.mimeType,
                      "created": str(attachment.created),  # 确保日期是字符串
                      "url": str(attachment.content),  # 确保URL是字符串
                      "local_path": local_path if exists_locally else None,
                      "exists_locally": exists_locally
                  })
          
          return {
              "issue_key": issue_key,
              "attachments": attachments,
              "total": len(attachments),
              "attachments_dir": os.path.join(ATTACHMENTS_DIR, issue_key)
          }
      except Exception as e:
          logger.error(f"获取问题 {issue_key} 附件列表失败: {str(e)}")
          return {"error": str(e)}

• src/jira_mcp/server.py:31-37 (helper)

  Helper utility to determine the local filesystem path for storing attachments of a specific JIRA issue.

  def get_attachment_path(issue_key: str, filename: str) -> str:
      """获取附件在本地文件系统中的保存路径."""
      # 创建问题专属目录
      issue_dir = os.path.join(ATTACHMENTS_DIR, issue_key)
      os.makedirs(issue_dir, exist_ok=True)
      return os.path.join(issue_dir, filename)

• src/jira_mcp/server.py:638-715 (helper)

  Supporting tool/helper invoked by get_issue_attachments when download parameter is True. Downloads all attachments to local directory and returns download results.

  @mcp.tool(
      description="下载JIRA问题的所有附件到本地",
  )
  def download_all_attachments(
      issue_key: str,
  ) -> Dict[str, Any]:
      """下载JIRA问题的所有附件到本地.
      
      Args:
          issue_key: JIRA问题键
      
      Returns:
          Dict[str, Any]: 下载结果
      """
      logger.info(f"下载问题所有附件: {issue_key}")
      try:
          client = get_jira_client()
          issue = client.issue(issue_key)
          
          downloads = []
          failed = []
          
          # 获取附件列表
          attachments = []
          if hasattr(issue.fields, "attachment") and issue.fields.attachment:
              attachments = issue.fields.attachment
          
          if not attachments:
              return {
                  "issue_key": issue_key,
                  "message": "此问题没有附件",
                  "total": 0,
                  "downloads": []
              }
          
          # 为此问题创建目录
          issue_dir = os.path.join(ATTACHMENTS_DIR, issue_key)
          os.makedirs(issue_dir, exist_ok=True)
          
          # 下载每个附件
          for attachment in attachments:
              try:
                  file_path = os.path.join(issue_dir, attachment.filename)
                  
                  # 下载内容
                  content = attachment.get()
                  
                  # 保存到文件
                  with open(file_path, "wb") as f:
                      f.write(content)
                  
                  downloads.append({
                      "id": attachment.id,
                      "filename": attachment.filename,
                      "size": os.path.getsize(file_path),
                      "content_type": attachment.mimeType,
                      "local_path": file_path
                  })
              except Exception as e:
                  logger.error(f"下载附件 {attachment.filename} 失败: {str(e)}")
                  failed.append({
                      "filename": attachment.filename,
                      "error": str(e)
                  })
          
          return {
              "issue_key": issue_key,
              "total": len(attachments),
              "success": len(downloads),
              "failed": len(failed),
              "download_dir": issue_dir,
              "downloads": downloads,
              "failures": failed if failed else None
          }
      except Exception as e:
          logger.error(f"下载问题 {issue_key} 的所有附件失败: {str(e)}")
          return {"error": str(e)}