JIRA

✨ Recursos

• 🎯 Suíte Completa de Integração com JIRA

  • Gerenciamento de Issues: Operações CRUD completas para issues do JIRA com suporte abrangente a campos
  • Descoberta de Projetos e Quadros: Navegue por projetos, quadros e sprints com filtros avançados
  • Busca Inteligente: Busca JQL e amigável para iniciantes com formatação rica
  • Sistema de Comentários: Acesse e gerencie comentários de issues com divulgação progressiva

• 🏗️ Arquitetura de Nível Empresarial (Novo na v0.5.0)

  • Design Modular: Arquitetura baseada em recursos com clara separação de responsabilidades
  • Cliente HTTP Robusto: Refatorado com classes utilitárias dedicadas para confiabilidade
  • Testes Abrangentes: Mais de 822 testes garantindo estabilidade e confiabilidade
  • Segurança de Tipos: Modo estrito TypeScript completo com tratamento de erros aprimorado

• 🔍 Busca e Descoberta Poderosas

  • Pesquise issues usando JQL (JIRA Query Language) ou parâmetros amigáveis para iniciantes
  • Descoberta de projetos, quadros e sprints com metadados e filtros
  • Formatação rica em markdown com pré-visualizações de issues e links de navegação diretos
  • Recuperação avançada de comentários com filtro por autor e intervalos de datas

• 📝 Gerenciamento Avançado de Issues

  • Crie, atualize e faça transições de issues com suporte abrangente a campos
  • Controle de tempo, gerenciamento de worklogs e suporte a campos personalizados
  • Análise de ADF (Atlassian Document Format) para exibição de conteúdo rico
  • Operações de array para labels, componentes e versões

🆕 Novidades na v0.5.0

🏗️ Grande Reformulação da Arquitetura

• Reorganização completa do código com arquitetura modular orientada a domínio
• Refatoração do cliente HTTP com classes utilitárias dedicadas para maior confiabilidade
• Correção crítica de bug para URLs da API JIRA malformadas que impediam a comunicação adequada

🧪 Testes e Qualidade Aprimorados

• Mais de 95 novos testes adicionados para utilitários do cliente HTTP e casos extremos
• 822 testes no total garantindo cobertura abrangente e estabilidade
• Zero avisos de linting com integração aprimorada com Biome

🔧 Melhorias Técnicas

• Tratamento de erros aprimorado com melhor classificação e mensagens acionáveis
• Registro de logs aprimorado com informações de depuração estruturadas e monitoramento de desempenho
• Aprimoramentos de segurança de tipos com verificação estrita de TypeScript em todo o código

🚀 Desempenho e Confiabilidade

• Requisições HTTP otimizadas com melhor gerenciamento de conexões
• Recuperação de erros aprimorada com lógica de repetição e tratamento de timeout melhorados
• Compatibilidade retroativa mantida — atualização sem interrupções a partir da v0.4.x

🚀 Início Rápido

Instalação

Adicione esta configuração ao seu cliente MCP:

{
  "mcpServers": {
    "JIRA Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-jira@latest"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

Configuração de Desenvolvimento

Para desenvolvimento e testes locais:

# Clone the repository
git clone https://github.com/Dsazz/mcp-jira.git
cd mcp-jira

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your JIRA credentials

# Build the project
bun run build

# Test with MCP Inspector
bun run inspect

Configuração

Crie um arquivo .env com as seguintes variáveis:

JIRA_HOST=https://your-instance.atlassian.net
JIRA_USERNAME=your-email@example.com
JIRA_API_TOKEN=your-jira-api-token-here

🔑 Nota Importante Sobre Tokens da API JIRA

• Um token da API JIRA pode ser gerado em Atlassian API Tokens
• Os tokens podem conter caracteres especiais, incluindo o sinal =
• Coloque o token em uma única linha no arquivo .env
• Não adicione aspas ao redor do valor do token
• Cole o token exatamente como fornecido pela Atlassian

🧰 Ferramentas Disponíveis

Ferramentas Principais do JIRA

Parâmetros de Criação de Issues

A ferramenta jira_create_issue suporta criação abrangente de issues:

Obrigatórios:

• projectKey: String — Chave do projeto (ex.: "PROJ")
• issueType: String — Tipo de issue (ex.: "Task", "Bug", "Story")
• summary: String — Título/resumo da issue

Campos Opcionais:

• description: String — Descrição detalhada (suporta formato ADF)
• priority: String — Nível de prioridade ("Highest", "High", "Medium", "Low", "Lowest")
• assignee: String — Nome de usuário ou e-mail do responsável
• reporter: String — Nome de usuário ou e-mail do relator
• labels: Array — Labels a aplicar na issue
• components: Array — Nomes dos componentes
• fixVersions: Array — Nomes das versões de correção
• affectsVersions: Array — Nomes das versões afetadas
• timeEstimate: String — Estimativa de tempo no formato JIRA (ex.: "2h", "1d 4h")
• dueDate: String — Data de vencimento no formato ISO
• environment: String — Descrição do ambiente
• customFields: Object — Valores de campos personalizados

Exemplos:

# Basic issue creation
jira_create_issue projectKey:"PROJ" issueType:"Task" summary:"Fix login bug"

# Comprehensive issue with all fields
jira_create_issue projectKey:"PROJ" issueType:"Bug" summary:"Critical login issue" description:"Users cannot log in" priority:"High" assignee:"john.doe" labels:["urgent","security"] timeEstimate:"4h"

Parâmetros de Atualização de Issues

A ferramenta jira_update_issue suporta atualizações abrangentes de issues:

Obrigatórios:

• issueKey: String — Chave da issue (ex.: "PROJ-123")

Atualizações de Campos (qualquer combinação):

• summary: String — Atualizar título da issue
• description: String — Atualizar descrição
• priority: String — Alterar prioridade
• assignee: String — Reatribuir issue
• reporter: String — Alterar relator
• timeEstimate: String — Atualizar estimativa de tempo
• timeSpent: String — Registrar tempo gasto
• dueDate: String — Atualizar data de vencimento
• environment: String — Atualizar ambiente

Operações de Array (adicionar/remover/definir):

• labels: Object — Modificar labels ({operation: "add|remove|set", values: ["label1", "label2"]})
• components: Object — Modificar componentes
• fixVersions: Object — Modificar versões de correção
• affectsVersions: Object — Modificar versões afetadas

Transições de Status:

• status: String — Transição para novo status (ex.: "In Progress", "Done")

Worklog:

• worklog: Object — Adicionar entrada de worklog ({timeSpent: "2h", comment: "Fixed issue"})

Exemplos:

# Update basic fields
jira_update_issue issueKey:"PROJ-123" summary:"Updated title" priority:"High"

# Add labels and transition status
jira_update_issue issueKey:"PROJ-123" labels:'{operation:"add",values:["urgent"]}' status:"In Progress"

# Log work and add comment
jira_update_issue issueKey:"PROJ-123" worklog:'{timeSpent:"2h",comment:"Completed testing"}'

Parâmetros de Projetos

A ferramenta jira_get_projects suporta descoberta de projetos:

Parâmetros Opcionais:

• maxResults: Number (1-100, padrão: 50) — Limitar número de resultados
• startAt: Number (padrão: 0) — Deslocamento de paginação
• expand: Array — Campos adicionais a incluir (["description", "lead", "issueTypes", "url", "projectKeys"])

Exemplos:

# Get all projects
jira_get_projects

# Get projects with additional details
jira_get_projects expand:["description","lead","issueTypes"] maxResults:20

Parâmetros de Quadros

A ferramenta jira_get_boards suporta gerenciamento de quadros:

Parâmetros Opcionais:

• maxResults: Number (1-100, padrão: 50) — Limitar número de resultados
• startAt: Number (padrão: 0) — Deslocamento de paginação
• type: String — Tipo de quadro ("scrum", "kanban")
• name: String — Filtrar por nome do quadro
• projectKeyOrId: String — Filtrar por projeto

Exemplos:

# Get all boards
jira_get_boards

# Get Scrum boards for specific project
jira_get_boards type:"scrum" projectKeyOrId:"PROJ"

# Search boards by name
jira_get_boards name:"Sprint Board" maxResults:10

Parâmetros de Sprints

A ferramenta jira_get_sprints suporta gerenciamento de sprints:

Obrigatórios:

• boardId: Number — ID do quadro para obter sprints

Parâmetros Opcionais:

• maxResults: Number (1-100, padrão: 50) — Limitar número de resultados
• startAt: Number (padrão: 0) — Deslocamento de paginação
• state: String — Estado do sprint ("active", "closed", "future")

Exemplos:

# Get all sprints for a board
jira_get_sprints boardId:123

# Get only active sprints
jira_get_sprints boardId:123 state:"active"

# Get sprints with pagination
jira_get_sprints boardId:123 maxResults:10 startAt:20

Parâmetros de Worklog

As ferramentas de worklog suportam controle de tempo abrangente:

Parâmetros de jira_add_worklog:

Obrigatórios:

• issueKey: String — Chave da issue (ex.: "PROJ-123")
• timeSpent: String — Tempo gasto no formato JIRA (ex.: "2h", "1d 4h", "30m")

Opcionais:

• comment: String — Comentário descrevendo o trabalho realizado
• started: String — Quando o trabalho começou (formato de data ISO, padrão: agora)
• visibility: Object — Configurações de visibilidade ({type: "group", value: "jira-developers"})

Parâmetros de jira_get_worklogs:

Obrigatórios:

• issueKey: String — Chave da issue (ex.: "PROJ-123")

Opcionais:

• startedAfter: String — Filtrar worklogs iniciados após esta data (formato ISO)
• startedBefore: String — Filtrar worklogs iniciados antes desta data (formato ISO)

Parâmetros de jira_update_worklog:

Obrigatórios:

• issueKey: String — Chave da issue (ex.: "PROJ-123")
• worklogId: String — ID do worklog a atualizar

Opcionais (qualquer combinação):

• timeSpent: String — Atualizar tempo gasto
• comment: String — Atualizar comentário
• started: String — Atualizar horário de início

Parâmetros de jira_delete_worklog:

Obrigatórios:

• issueKey: String — Chave da issue (ex.: "PROJ-123")
• worklogId: String — ID do worklog a excluir

Exemplos:

# Add worklog entry
jira_add_worklog issueKey:"PROJ-123" timeSpent:"2h" comment:"Fixed authentication bug"

# Get all worklogs for an issue
jira_get_worklogs issueKey:"PROJ-123"

# Get worklogs from last week
jira_get_worklogs issueKey:"PROJ-123" startedAfter:"2025-05-29T00:00:00.000Z"

# Update worklog
jira_update_worklog issueKey:"PROJ-123" worklogId:"12345" timeSpent:"3h" comment:"Updated work description"

# Delete worklog
jira_delete_worklog issueKey:"PROJ-123" worklogId:"12345"

Parâmetros de Comentários

A ferramenta jira_get_issue_comments suporta divulgação progressiva com estes parâmetros:

Obrigatórios:

• issueKey: String — Chave da issue (ex.: "PROJ-123")

Opções Básicas:

• maxComments: Number (1-100, padrão: 10) — Número máximo de comentários a recuperar
• orderBy: String ("created" ou "updated", padrão: "created") — Ordem de classificação dos comentários

Opções Avançadas:

• includeInternal: Booleano (padrão: false) - Incluir comentários internos/restritos
• authorFilter: String - Filtrar comentários por nome ou e-mail do autor
• dateRange: Objeto - Filtrar por intervalo de datas:
  • from: String (data ISO) - Data inicial
  • to: String (data ISO) - Data final

Exemplos:

# Basic usage - get 10 most recent comments
jira_get_issue_comments PROJ-123

# Get more comments with specific ordering
jira_get_issue_comments PROJ-123 maxComments:25 orderBy:"updated"

# Advanced filtering
jira_get_issue_comments PROJ-123 authorFilter:"john.doe" includeInternal:true

Parâmetros de Busca

A ferramenta search_jira_issues suporta dois modos:

Modo Especialista (JQL):

• jql: String de consulta JQL direta (ex.: "project = PROJ AND status = Open")

Modo Iniciante (Parâmetros Auxiliares):

• assignedToMe: Booleano - Mostrar apenas issues atribuídas ao usuário atual
• project: String - Filtrar por chave do projeto
• status: String ou Array - Filtrar por status (ex.: "Open" ou ["Open", "In Progress"])
• text: String - Pesquisar nos campos de resumo e descrição

Opções Comuns:

• maxResults: Número (1-50, padrão: 25) - Limitar número de resultados
• fields: Array - Especificar quais campos recuperar (opcional)

🛠️ Ferramentas de Desenvolvimento

Ferramentas de Qualidade de Código

O projeto usa Biome para formatação e linting de código, oferecendo:

• Formatação e linting rápidos e unificados
• Ferramentas priorizando TypeScript
• Zero configuração necessária
• Aplicação consistente do estilo de código

# Format code
bun run format

# Check code for issues
bun run check

# Type check
bun run typecheck

# Run tests
bun test

MCP Inspector

# Run the inspector (no separate build step needed)
bun run inspect

bun run cleanup-ports

Integração com Claude Desktop

🔌 Integração com Cursor IDE

⚠️ Importante: Você deve compilar o projeto com bun run build antes de integrar com Cursor IDE ou Claude Desktop.

Adicione este servidor MCP à configuração MCP do seu Cursor IDE:

{
  "mcpServers": {
    "JIRA Tools": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"],
      "env": {
        "JIRA_USERNAME": "your-jira-username",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "JIRA_HOST": "your-jira-host.atlassian.net"
      }
    }
  }
}

📁 Estrutura do Projeto

src/
├── core/                    # Core functionality and configurations
│   ├── errors/             # Error handling utilities
│   ├── logging/            # Logging infrastructure
│   ├── responses/          # Response formatting
│   ├── server/             # MCP server implementation
│   ├── tools/              # Base tool interfaces
│   └── utils/              # Core utilities
├── features/               # Feature implementations
│   └── jira/              # JIRA API integration
│       ├── api/           # JIRA API client
│       ├── formatters/    # Response formatters
│       ├── tools/         # MCP tool implementations
│       └── utils/         # JIRA-specific utilities
└── test/                  # Test utilities and mocks
    ├── mocks/             # Mock factories
    └── utils/             # Test helpers

Scripts NPM

📝 Contribuindo

Aceitamos contribuições! Consulte nosso Guia de Contribuição para detalhes sobre:

• Fluxo de trabalho de desenvolvimento
• Estratégia de branches
• Formato de mensagens de commit
• Processo de pull requests
• Diretrizes de estilo de código

📘 Recursos

• Documentação do Model Context Protocol
• SDK TypeScript do MCP
• Especificação do MCP
• MCP Inspector
• Documentação da API REST do JIRA

📄 Licença

MIT © Stanislav Stepanenko