Jira-pilot

CLI e servidor MCP com IA para Jira, voltado para humanos e agentes gerenciarem issues, sprints e quadros com assistentes interativos e IA de múltiplos provedores.

GitHub

Experimente este MCPPatrocinado

Documentação

Jira Pilot ✈️

O CLI de Jira com IA e Servidor MCP para Humanos e Agentes.

jira-pilot é um CLI de próxima geração que combina ferramentas de desenvolvimento tradicionais com capacidades modernas de IA.

Para Humanos: Um CLI bonito e interativo para gerenciar issues, sprints, quadros e código. Agora com Revisões de Código com IA, Planejamento de Épicos, Daily Standups e JQL em Linguagem Natural.
Para Agentes: Um servidor Model Context Protocol (MCP) totalmente compatível com 14 ferramentas que permite que assistentes de IA (como Claude Desktop, Cursor ou Gemini) interajam com sua instância do Jira com segurança.

Recursos em Destaque

👤 Recursos Centrados no Humano

Recurso	Descrição
Gerenciamento de Issues	Criar, editar, visualizar, listar, transicionar, atribuir e comentar em issues
Trabalho e Tempo	Novo: Registrar trabalho (`2h 30m`), gerenciar sprints (iniciar/concluir) e subtarefas
Ferramentas de Desenvolvedor	Novo: Abrir PRs, salvar filtros locais, integração com branches git
Ferramentas Avançadas	Novo: Atribuição em massa, etiquetas em massa, transição em massa com correspondência JQL
Dados Avançados	Novo: Enviar anexos, gerenciar campos personalizados por alias
Copiloto de IA	Resumir, redigir descrições, sugerir ações, revisar código, planejar épicos, relatórios de standup
Assistentes Interativos	Prompts passo a passo com `enquirer` — sem necessidade de flags
Visualização Rica	Visão geral do painel, spinners e saída formatada
Exportação	Saída para arquivos JSON ou Markdown, saída JSON encadeável

🤖 Recursos de Agentes (MCP)

Recurso	Descrição
14 Ferramentas MCP	list_issues, get_issue, create_issue, update_issue, transition_issue, assign_issue, add_comment, add_worklog, create_subtask, add_attachment, search_users, myself, list_projects, list_sprints
Otimizado para LLM	Respostas JSON limpas e estruturadas para uso eficiente de tokens
Transporte Stdio	Servidor MCP stdio padrão — funciona com qualquer cliente MCP

🚀 Instalação

Pré-requisitos

Node.js 20.0.0 ou superior

Instalação Global (Recomendado)

npm install -g jira-pilot

Após a instalação, o comando jira estará disponível globalmente.

⚙️ Configuração

Antes de usar a ferramenta, configure suas credenciais. Você pode obter um Token de API em Configurações da Conta Atlassian.

Configuração Inicial

jira config setup

Você será solicitado a fornecer:

URL do Site Jira — ex.: https://your-company.atlassian.net
E-mail — O e-mail da sua conta Atlassian
Token de API — O token que você gerou na Atlassian
Ativar IA — Ativar/desativar recursos de IA
Provedor de IA — Escolha entre openai, gemini ou anthropic
Chave de API de IA — Sua chave de API para o provedor selecionado

Perfis e Gerenciamento

Gerencie credenciais para vários ambientes (ex.: Trabalho vs. Pessoal, Produção vs. Desenvolvimento).

jira config view              # Show current configuration (keys are masked)
jira config save work         # Save current creds as profile 'work'
jira config use personal      # Switch to profile 'personal'
jira config profiles          # List all saved profiles
jira config delete-profile work
jira config clear             # Remove all stored credentials

Aliases de Campos Personalizados

Defina aliases para IDs de campos personalizados para facilitar os comandos:

jira config field set points customfield_10011
jira config field list

✨ Experiência Interativa

O Jira Pilot foi projetado para ser totalmente interativo. Você não precisa lembrar de flags complexas.

Basta executar o comando, e nós o guiaremos:

Seleção: Use as teclas de seta ↑ ↓ para navegar pelas listas (Projetos, Tipos de Issue, Prioridades).
Filtragem: Comece a digitar para filtrar listas longas (ex.: encontrar um responsável específico).
Assistentes: Fluxos complexos, como criar uma issue, são divididos em etapas simples.
Confirmação: Ações destrutivas solicitam confirmação (s/N).

Exemplo:

jira issue create
? Select Project: PROJ - My Project
? Select Issue Type: Bug
? Summary: Login page crashes
? Priority: High
? Assignee: Me

🖥️ Interface de Usuário de Texto (TUI)

Experimente o Jira em uma interface de terminal interativa e persistente.

jira tui

Recursos Principais:

Painel: Visão geral do seu trabalho atribuído.
Navegador de Issues: Navegue, filtre e visualize issues.
Quadros Kanban: Visualize e gerencie o trabalho em quadros ágeis.
Interativo: Use as teclas de seta para navegar por linhas e colunas.

Atalhos de Navegação:

← / → : Alternar Abas (Painel, Issues, Quadros) ou Colunas do Quadro
↑ / ↓ : Navegar pelas Listas
Enter : Selecionar / Ver Detalhes
Esc / b : Voltar
q : Sair

📊 Meu Painel

Comece o dia com uma visão geral de alto nível do que está na sua lista.

jira dashboard

O que você verá:

👋 Mensagem de Boas-vindas: Saudação personalizada.
🔥 Alta Prioridade: Issues atribuídas a você que precisam de atenção imediata.
📋 Atividade Recente: Suas issues visualizadas ou atualizadas recentemente.
🚀 Status do Sprint: (Se aplicável) Progresso do sprint ativo.

📖 Guia de Uso

📋 Gerenciamento de Issues

Listar Issues

# List issues assigned to you in active sprints (interactive)
jira issue list

# List with custom JQL
jira issue list --jql "project = PROJ AND priority = High"

# Filter by project, assignee, or status via flags
jira issue list --project PROJ --assignee "john.doe" --status "In Progress"

# Limit results
jira issue list --limit 20

# Natural Language JQL (AI)
jira issue list --ask "high priority bugs assigned to me"

# Export results to file
jira issue list --export json    # Creates issues-TIMESTAMP.json
jira issue list --export md      # Creates issues-TIMESTAMP.md

# Pipeable JSON output (to stdout)
jira issue list --output json | jq .

Pesquisar Issues

Pesquisa rápida de texto usando JQL text ~ "query":

jira issue search "login bug"
jira issue search "error 500" --project PROJ

Visualizar Detalhes da Issue

jira issue view PROJ-123

Exibe: resumo, status, prioridade, responsável, descrição, componentes, etiquetas, datas, versões e comentários recentes.

Criar Issue

# Interactive wizard (recommended)
jira issue create

# Non-interactive with flags for speed
jira issue create -p PROJ -s "Fix login bug"
jira issue create -p PROJ -t Bug -s "Crash on save" --priority High
jira issue create -p PROJ -t Story -s "Add dark mode" -d "Users want a dark theme" -a me

# With Custom Fields (using Alias or ID)
jira issue create -p PROJ -s "Story" --custom "points=5" --custom "customfield_10022=DevOps"

Editar Issue

# Interactive Field Picker
jira issue edit PROJ-123

# Quick Edits
jira issue edit PROJ-123 -s "New Summary" --priority High
jira issue edit PROJ-123 -d "New description"
jira issue edit PROJ-123 --custom "points=8"

Transicionar Status da Issue

# Interactive — shows available transitions
jira issue transition PROJ-123

# Direct — specify target status
jira issue transition PROJ-123 --status "In Progress"
jira issue transition PROJ-123 -s Done

Atribuir / Reatribuir

# Interactive — choose Myself, Unassign, or Search
jira issue assign PROJ-123

# Quick assign
jira issue assign PROJ-123 -a me       # Assign to yourself
jira issue assign PROJ-123 -a none     # Unassign

Adicionar Comentário

# Interactive — prompts for comment text
jira issue comment PROJ-123

# Inline comment
jira issue comment PROJ-123 -m "Fixed in latest build"

Outras Ações

# Link Issues
jira issue link PROJ-123 PROJ-456 -t Blocks

# Watchers
jira issue watch PROJ-123
jira issue unwatch PROJ-123

# Attachments
jira issue attach PROJ-123 ./logs/server.log

⏱️ Trabalho e Tempo

Registros de Trabalho

Acompanhe o tempo naturalmente em relação às issues.

# Add worklog
jira issue worklog add PROJ-123 2h "Researching API"
jira issue worklog add PROJ-123 30m "Daily standup"
jira issue worklog add PROJ-123 1d "Implementation"

# List worklogs
jira issue worklog list PROJ-123

Subtarefas

# Interactive subtask creation
jira issue subtask PARENT-123

# Quick subtask
jira issue subtask PARENT-123 -s "Implement backend logic" --assignee me

Gerenciamento de Sprints

Gerencie seus quadros ágeis diretamente.

# List sprints
jira sprint list --board "My Board"
jira sprint list --board 5 --state active

# List issues in active sprint
jira sprint issues --board 5

# Start/Complete Sprints
jira sprint start 123 --start-date 2023-10-01 --end-date 2023-10-15
jira sprint complete 123

👨‍💻 Fluxo de Trabalho do Desenvolvedor

Pull Requests

Abra um PR no GitHub com título e corpo pré-preenchidos a partir da issue do Jira.

jira issue pr PROJ-123
# Requires 'gh' CLI to be installed and authenticated

Integração com Git

Crie branches de recursos automaticamente nomeados a partir do resumo da issue.

jira git branch PROJ-123
# Creates: feature/PROJ-123-issue-summary-slug

Filtros Salvos

Salve consultas JQL complexas localmente para acesso rápido.

# Save a filter
jira filter save "My Bugs" "assignee = currentUser() AND issuetype = Bug AND status != Done"

# List saved filters
jira filter list

# Use a saved filter
jira issue list --filter "My Bugs"

# Delete a filter
jira filter delete "My Bugs"

⚡ Ferramentas Avançadas (Ações em Massa)

Execute ações em várias issues que correspondem a uma consulta JQL. Ótimo para limpezas ou atualizações em massa.

Transição em Massa

Mova várias issues para um novo status.

jira bulk transition -j "project = PROJ AND status = 'To Do'" -s "In Progress"
# Optional: -y to skip confirmation

Atribuição em Massa

Atribua um conjunto de issues a um usuário.

jira bulk assign -j "priority = High AND assignee is EMPTY" --assignee me

Etiquetas em Massa

Adicione ou remova etiquetas de um conjunto de issues.

jira bulk label -j "fixVersion = 1.0" --add "release-candidate" --remove "wip"

📂 Projetos e Quadros

Listar Projetos

jira project list
# Displays: project key, name, lead, and style in a formatted table.

Listar Quadros

# List all boards
jira board list

# Filter by project
jira board list -p PROJ

# Filter by type
jira board list -t scrum
jira board list -t kanban

🤖 Recursos de IA

Requer: IA ativada em config setup.

Resumir uma Issue

Obtenha um resumo gerado por IA (TL;DR) de threads longas de issues com comentários:

jira ai summarize PROJ-123

Redigir uma Descrição de Issue

Gere uma descrição estruturada de issue a partir de anotações ou tópicos:

# Interactive — prompts for your notes
jira ai draft

# Inline with issue type context
jira ai draft -i "login fails, returns 500, only on mobile" -t bug
jira ai draft -i "add dark mode toggle to settings" -t story

Sugerir Próximas Ações

Analise uma issue e obtenha sugestões com IA para o que fazer em seguida:

jira ai suggest PROJ-123

Retorna: Próxima Ação Imediata, Possíveis Bloqueios, Transição de Status Sugerida e Recomendações.

Revisão de Código com IA

Analise PRs/alterações de código vinculadas em relação aos requisitos da issue:

jira ai review PROJ-123

Requer githubToken na configuração.

Planejamento de Épicos com IA

Divida um Épico em Histórias/Tarefas filhas e crie-as em massa:

jira ai plan EPIC-123    # Interactive selection of proposed tasks

Relatório de Standup com IA

Gere um standup diário com base na sua atividade recente:

jira ai standup

Saídas: Ontem, Hoje, Bloqueios.

🧠 Usando com Agentes de IA (MCP)

jira-pilot implementa o Model Context Protocol (MCP), tornando-o plug-and-play para assistentes de IA.

Iniciando o Servidor MCP

jira mcp

Ferramentas MCP Disponíveis (14)

Tudo o que você precisa para construir um agente Jira totalmente autônomo:

jira_list_issues: Pesquisar via JQL (suporta limite)
jira_get_issue: Obter detalhes completos
jira_create_issue: Criar nova issue (suporte ADF)
jira_update_issue: Atualizar resumo, descrição, prioridade, responsável
jira_transition_issue: Alterar status
jira_assign_issue: Alterar responsável
jira_add_comment: Adicionar comentário
jira_add_worklog: Registrar tempo
jira_create_subtask: Criar subtarefa
jira_add_attachment: Enviar arquivo (caminho absoluto)
jira_search_users: Pesquisar usuários
jira_myself: Obter detalhes do usuário atual
jira_list_projects: Listar projetos acessíveis
jira_list_sprints: Listar sprints de um quadro

Configuração do Agente (Claude Desktop)

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-pilot", "mcp"]
    }
  }
}

Configuração VS Code / Cursor

Adicione ao seu .vscode/mcp.json ou equivalente:

{
  "servers": {
    "jira-pilot": {
      "command": "jira",
      "args": ["mcp"]
    }
  }
}

📝 Prompts

Modelos pré-definidos para ajudar LLMs a interagir com o Jira de forma eficaz.

Prompt	Argumentos	Descrição
jira-assist	Nenhum	Prompt de sistema que ensina o LLM a usar melhor as ferramentas do Jira Pilot.
jira-summarize-issue	`issueKey`	Busca uma issue e instrui o LLM a fornecer um resumo conciso.

📦 Recursos

Acesso direto aos dados do Jira como contexto.

URI	Descrição
jira://myself	Detalhes do usuário atualmente autenticado (excluindo PII sensível).
jira://projects	Lista de todos os projetos Jira acessíveis.

🔍 Verificação

Você pode verificar a implementação do servidor MCP usando o inspetor oficial:

# If running fro source
npx @modelcontextprotocol/inspector node dist/bin/jira.js mcp

# If installed globally (or via npx)
npx @modelcontextprotocol/inspector npx -y jira-pilot mcp

📦 Referência de Comandos CLI

Execute jira help ou jira [command] help para ver todas as opções.

jira [command]

Commands:
  config           Configure Jira credentials & profiles
  issue            Manage Jira issues
  project          Manage Jira projects
  board            Manage Jira boards
  sprint           Manage Sprints
  bulk             Bulk operations on Jira issues
  dashboard        Show a quick overview of your Jira activity
  git              Git integration for Jira
  ai               AI Helper commands
  mcp              Start MCP Agent Server (Stdio)

🤝 Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para obter detalhes sobre como enviar um pull request e configurar seu ambiente de desenvolvimento.

Observe que este projeto é lançado com um Código de Conduta do Contribuidor. Ao participar deste projeto, você concorda em cumprir seus termos.

🛡️ Segurança

Se você descobrir uma vulnerabilidade de segurança neste projeto, consulte SECURITY.md para nossa política de relatórios.

📄 Licença

ISC