Jira-pilot

CLI de Jira con IA y servidor MCP para que humanos y agentes gestionen incidencias, sprints y tableros con asistentes interactivos e IA de múltiples proveedores.

GitHub

Prueba este MCPPatrocinado

Documentación

Jira Pilot ✈️

El CLI de Jira y Servidor MCP impulsado por IA para Humanos y Agentes.

jira-pilot es un CLI de próxima generación que combina herramientas de desarrollo tradicionales con capacidades modernas de IA.

Para Humanos: Un CLI hermoso e interactivo para gestionar incidencias, sprints, tableros y código. Ahora con Revisiones de Código con IA, Planificación de Épicas, Reuniones Diarias y JQL en Lenguaje Natural.
Para Agentes: Un servidor Model Context Protocol (MCP) totalmente compatible con 14 herramientas que permite a los asistentes de IA (como Claude Desktop, Cursor o Gemini) interactuar con tu instancia de Jira de forma segura.

Características de un Vistazo

👤 Características Centradas en Humanos

Característica	Descripción
Gestión de Incidencias	Crear, editar, ver, listar, transicionar, asignar y comentar incidencias
Trabajo y Tiempo	Nuevo: Registrar trabajo (`2h 30m`), gestionar sprints (iniciar/completar) y subtareas
Herramientas de Desarrollo	Nuevo: Abrir PRs, guardar filtros locales, integración con ramas de git
Herramientas Avanzadas	Nuevo: Asignación masiva, etiquetado masivo, transición masiva con JQL
Datos Avanzados	Nuevo: Subir adjuntos, gestionar campos personalizados por alias
Copiloto de IA	Resumir, redactar descripciones, sugerir acciones, revisar código, planificar épicas, informes de reuniones diarias
Asistentes Interactivos	Indicaciones paso a paso con `enquirer` — sin necesidad de banderas
Visualización Enriquecida	Resumen del panel, indicadores de progreso y salida formateada
Exportación	Salida a archivos JSON o Markdown, salida JSON encadenable

🤖 Características para Agentes (MCP)

Característica	Descripción
14 Herramientas 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
Optimizado para LLM	Respuestas JSON limpias y estructuradas para un uso eficiente de tokens
Transporte Stdio	Servidor MCP stdio estándar — funciona con cualquier cliente MCP

🚀 Instalación

Requisitos Previos

Node.js 20.0.0 o superior

Instalación Global (Recomendada)

npm install -g jira-pilot

Después de instalar, el comando jira está disponible globalmente.

⚙️ Configuración

Antes de usar la herramienta, configura tus credenciales. Puedes obtener un Token de API desde Configuración de la Cuenta Atlassian.

Configuración Inicial

jira config setup

Se te pedirá:

URL del Sitio de Jira — p. ej., https://your-company.atlassian.net
Correo Electrónico — El correo de tu cuenta Atlassian
Token de API — El token que generaste desde Atlassian
Habilitar IA — Activar o desactivar las funciones de IA
Proveedor de IA — Elige entre openai, gemini o anthropic
Clave de API de IA — Tu clave de API para el proveedor seleccionado

Perfiles y Gestión

Gestiona credenciales para múltiples entornos (p. ej., Trabajo vs. Personal, Producción vs. Desarrollo).

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

Alias de Campos Personalizados

Define alias para IDs de campos personalizados para facilitar los comandos:

jira config field set points customfield_10011
jira config field list

✨ Experiencia Interactiva

Jira Pilot está diseñado para ser totalmente interactivo. No necesitas recordar banderas complejas.

Solo ejecuta el comando y te guiaremos:

Selección: Usa las teclas de flecha ↑ ↓ para navegar por las listas (Proyectos, Tipos de Incidencia, Prioridades).
Filtrado: Comienza a escribir para filtrar listas largas (p. ej., encontrar un asignado específico).
Asistentes: Los flujos complejos como crear una incidencia se dividen en pasos simples.
Confirmación: Las acciones destructivas solicitan confirmación (s/N).

Ejemplo:

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

🖥️ Interfaz de Usuario de Texto (TUI)

Experimenta Jira en una interfaz de terminal persistente e interactiva.

jira tui

Características Clave:

Panel: Resumen de tu trabajo asignado.
Navegador de Incidencias: Explora, filtra y visualiza incidencias.
Tableros Kanban: Visualiza y gestiona el trabajo en tableros ágiles.
Interactivo: Usa las teclas de flecha para navegar por filas y columnas.

Atajos de Navegación:

← / → : Cambiar Pestañas (Panel, Incidencias, Tableros) o Columnas del Tablero
↑ / ↓ : Navegar Listas
Enter : Seleccionar / Ver Detalles
Esc / b : Atrás
q : Salir

📊 Mi Panel

Comienza tu día con una visión general de alto nivel de lo que tienes pendiente.

jira dashboard

Lo que verás:

👋 Mensaje de Bienvenida: Saludo personalizado.
🔥 Alta Prioridad: Incidencias asignadas a ti que requieren atención inmediata.
📋 Actividad Reciente: Tus incidencias vistas o actualizadas recientemente.
🚀 Estado del Sprint: (Si aplica) Progreso del sprint activo.

📖 Guía de Uso

📋 Gestión de Incidencias

Listar Incidencias

# 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 .

Buscar Incidencias

Búsqueda rápida de texto usando JQL text ~ "query":

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

Ver Detalles de la Incidencia

jira issue view PROJ-123

Muestra: resumen, estado, prioridad, asignado, descripción, componentes, etiquetas, fechas, versiones y comentarios recientes.

Crear Incidencia

# 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 Incidencia

# 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 Estado de la Incidencia

# 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

Asignar / Reasignar

# 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

Añadir Comentario

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

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

Otras Acciones

# 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

⏱️ Trabajo y Tiempo

Registros de Trabajo

Registra tiempo de forma natural contra las incidencias.

# 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

Subtareas

# Interactive subtask creation
jira issue subtask PARENT-123

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

Gestión de Sprints

Gestiona tus tableros ágiles directamente.

# 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

👨‍💻 Flujo de Trabajo del Desarrollador

Solicitudes de Extracción (PRs)

Abre un PR de GitHub con título y cuerpo prellenados desde la incidencia de Jira.

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

Integración con Git

Crea ramas de características automáticamente nombradas desde el resumen de la incidencia.

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

Filtros Guardados

Guarda consultas JQL complejas localmente para acceso 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"

⚡ Herramientas Avanzadas (Acciones Masivas)

Realiza acciones en múltiples incidencias que coincidan con una consulta JQL. Ideal para limpiezas o actualizaciones masivas.

Transición Masiva

Mueve múltiples incidencias a un nuevo estado.

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

Asignación Masiva

Asigna un conjunto de incidencias a un usuario.

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

Etiquetado Masivo

Añade o elimina etiquetas de un conjunto de incidencias.

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

📂 Proyectos y Tableros

Listar Proyectos

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

Listar Tableros

# 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

🤖 Funciones de IA

Requiere: IA habilitada en config setup.

Resumir una Incidencia

Obtén un TL;DR generado por IA de hilos de incidencias largos con comentarios:

jira ai summarize PROJ-123

Redactar una Descripción de Incidencia

Genera una descripción estructurada de la incidencia a partir de notas aproximadas o viñetas:

# 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 Acciones

Analiza una incidencia y obtén sugerencias impulsadas por IA sobre qué hacer a continuación:

jira ai suggest PROJ-123

Devuelve: Próxima Acción Inmediata, Posibles Bloqueadores, Transición de Estado Sugerida y Recomendaciones.

Revisión de Código con IA

Analiza PRs/cambios de código vinculados contra los requisitos de la incidencia:

jira ai review PROJ-123

Requiere githubToken en la configuración.

Planificación de Épicas con IA

Desglosa una Épica en Historias/Tareas hijas y créalas de forma masiva:

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

Informe de Reunión Diaria con IA

Genera una reunión diaria basada en tu actividad reciente:

jira ai standup

Salidas: Ayer, Hoy, Bloqueadores.

🧠 Uso con Agentes de IA (MCP)

jira-pilot implementa el Model Context Protocol (MCP), lo que lo hace plug-and-play para asistentes de IA.

Iniciar el Servidor MCP

jira mcp

Herramientas MCP Disponibles (14)

Todo lo que necesitas para construir un agente de Jira totalmente autónomo:

jira_list_issues: Buscar mediante JQL (admite límite)
jira_get_issue: Obtener detalles completos
jira_create_issue: Crear nueva incidencia (soporte ADF)
jira_update_issue: Actualizar resumen, descripción, prioridad, asignado
jira_transition_issue: Cambiar estado
jira_assign_issue: Cambiar asignado
jira_add_comment: Añadir comentario
jira_add_worklog: Registrar tiempo
jira_create_subtask: Crear subtarea
jira_add_attachment: Subir archivo (ruta absoluta)
jira_search_users: Buscar usuarios
jira_myself: Obtener detalles del usuario actual
jira_list_projects: Listar proyectos accesibles
jira_list_sprints: Listar sprints de un tablero

Configuración del Agente (Claude Desktop)

Añade a tu claude_desktop_config.json:

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

Configuración de VS Code / Cursor

Añade a tu .vscode/mcp.json o equivalente:

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

📝 Indicaciones

Plantillas predefinidas para ayudar a los LLM a interactuar con Jira de manera efectiva.

Indicación	Argumentos	Descripción
jira-assist	Ninguno	Indicación del sistema que enseña al LLM cómo usar mejor las herramientas de Jira Pilot.
jira-summarize-issue	`issueKey`	Obtiene una incidencia e instruye al LLM para proporcionar un resumen conciso.

📦 Recursos

Acceso directo a los datos de Jira como contexto.

URI	Descripción
jira://myself	Detalles del usuario autenticado actualmente (excluyendo PII sensible).
jira://projects	Lista de todos los proyectos de Jira accesibles.

🔍 Verificación

Puedes verificar la implementación del servidor MCP usando el inspector 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

📦 Referencia de Comandos CLI

Ejecuta jira help o jira [command] help para ver todas las opciones.

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)

🤝 Contribuciones

¡Agradecemos las contribuciones! Consulta CONTRIBUTING.md para obtener detalles sobre cómo enviar una solicitud de extracción y configurar tu entorno de desarrollo.

Ten en cuenta que este proyecto se publica con un Código de Conducta del Contribuyente. Al participar en este proyecto, aceptas cumplir con sus términos.

🛡️ Seguridad

Si descubres una vulnerabilidad de seguridad dentro de este proyecto, consulta SECURITY.md para conocer nuestra política de reporte.

📄 Licencia

ISC