JIRA

✨ Características

• 🎯 Suite completa de integración con JIRA

  • Gestión de incidencias: operaciones CRUD completas para incidencias de JIRA con soporte integral de campos
  • Descubrimiento de proyectos y tableros: explora proyectos, tableros y sprints con filtrado avanzado
  • Búsqueda inteligente: búsqueda con JQL y apta para principiantes con formato enriquecido
  • Sistema de comentarios: accede y gestiona comentarios de incidencias con divulgación progresiva

• 🏗️ Arquitectura de nivel empresarial (Nuevo en v0.5.0)

  • Diseño modular: arquitectura basada en funcionalidades con clara separación de responsabilidades
  • Cliente HTTP robusto: refactorizado con clases de utilidad dedicadas para mayor fiabilidad
  • Pruebas exhaustivas: más de 822 pruebas que garantizan estabilidad y fiabilidad
  • Seguridad de tipos: modo estricto completo de TypeScript con manejo de errores mejorado

• 🔍 Búsqueda y descubrimiento potentes

  • Busca incidencias usando JQL (JIRA Query Language) o parámetros aptos para principiantes
  • Descubrimiento de proyectos, tableros y sprints con metadatos y filtrado
  • Formato Markdown enriquecido con vistas previas de incidencias y enlaces de navegación directa
  • Recuperación avanzada de comentarios con filtrado por autor y rangos de fechas

• 📝 Gestión avanzada de incidencias

  • Crea, actualiza y transiciona incidencias con soporte integral de campos
  • Seguimiento de tiempo, gestión de registros de trabajo y soporte de campos personalizados
  • Análisis de ADF (Atlassian Document Format) para mostrar contenido enriquecido
  • Operaciones de matrices para etiquetas, componentes y versiones

🆕 Novedades en v0.5.0

🏗️ Reestructuración importante de la arquitectura

• Reorganización completa del código con arquitectura modular basada en dominios
• Refactorización del cliente HTTP con clases de utilidad dedicadas para mayor fiabilidad
• Corrección crítica de errores en URL de API de JIRA mal formadas que impedían la comunicación adecuada

🧪 Pruebas y calidad mejoradas

• Más de 95 nuevas pruebas añadidas para utilidades del cliente HTTP y casos límite
• 822 pruebas en total que garantizan cobertura integral y estabilidad
• Cero advertencias de linting con integración mejorada de Biome

🔧 Mejoras técnicas

• Manejo de errores mejorado con mejor clasificación y mensajes accionables
• Registro mejorado con información de depuración estructurada y monitoreo de rendimiento
• Mejoras de seguridad de tipos con verificación estricta de TypeScript en todo el código

🚀 Rendimiento y fiabilidad

• Solicitudes HTTP optimizadas con mejor gestión de conexiones
• Recuperación de errores mejorada con lógica de reintentos y manejo de tiempos de espera mejorados
• Compatibilidad hacia atrás mantenida: actualización sin problemas desde v0.4.x

🚀 Inicio rápido

Instalación

Añade esta configuración a tu 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"
      }
    }
  }
}

Configuración de desarrollo

Para desarrollo y pruebas locales:

# 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

Configuración

Crea un archivo .env con las siguientes variables:

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

🔑 Nota importante sobre los tokens de API de JIRA

• Se puede generar un token de API de JIRA en Atlassian API Tokens
• Los tokens pueden contener caracteres especiales, incluido el signo =
• Coloca el token en una sola línea en el archivo .env
• No añadas comillas alrededor del valor del token
• Pega el token exactamente como lo proporciona Atlassian

🧰 Herramientas disponibles

Herramientas principales de JIRA

Parámetros de creación de incidencias

La herramienta jira_create_issue admite la creación integral de incidencias:

Obligatorios:

• projectKey: Cadena: clave de proyecto (p. ej., "PROJ")
• issueType: Cadena: tipo de incidencia (p. ej., "Task", "Bug", "Story")
• summary: Cadena: título/resumen de la incidencia

Campos opcionales:

• description: Cadena: descripción detallada (admite formato ADF)
• priority: Cadena: nivel de prioridad ("Highest", "High", "Medium", "Low", "Lowest")
• assignee: Cadena: nombre de usuario o correo electrónico del asignado
• reporter: Cadena: nombre de usuario o correo electrónico del informante
• labels: Matriz: etiquetas para aplicar a la incidencia
• components: Matriz: nombres de componentes
• fixVersions: Matriz: nombres de versiones de corrección
• affectsVersions: Matriz: nombres de versiones afectadas
• timeEstimate: Cadena: estimación de tiempo en formato JIRA (p. ej., "2h", "1d 4h")
• dueDate: Cadena: fecha de vencimiento en formato ISO
• environment: Cadena: descripción del entorno
• customFields: Objeto: valores de campos personalizados

Ejemplos:

# 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 actualización de incidencias

La herramienta jira_update_issue admite actualizaciones integrales de incidencias:

Obligatorios:

• issueKey: Cadena: clave de incidencia (p. ej., "PROJ-123")

Actualizaciones de campos (cualquier combinación):

• summary: Cadena: actualizar el título de la incidencia
• description: Cadena: actualizar la descripción
• priority: Cadena: cambiar la prioridad
• assignee: Cadena: reasignar la incidencia
• reporter: Cadena: cambiar el informante
• timeEstimate: Cadena: actualizar la estimación de tiempo
• timeSpent: Cadena: registrar el tiempo dedicado
• dueDate: Cadena: actualizar la fecha de vencimiento
• environment: Cadena: actualizar el entorno

Operaciones de matrices (añadir/eliminar/establecer):

• labels: Objeto: modificar etiquetas ({operation: "add|remove|set", values: ["label1", "label2"]})
• components: Objeto: modificar componentes
• fixVersions: Objeto: modificar versiones de corrección
• affectsVersions: Objeto: modificar versiones afectadas

Transiciones de estado:

• status: Cadena: transición a un nuevo estado (p. ej., "In Progress", "Done")

Registro de trabajo:

• worklog: Objeto: añadir entrada de registro de trabajo ({timeSpent: "2h", comment: "Fixed issue"})

Ejemplos:

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

La herramienta jira_get_projects admite el descubrimiento de proyectos:

Parámetros opcionales:

• maxResults: Número (1-100, predeterminado: 50): limita el número de resultados
• startAt: Número (predeterminado: 0): desplazamiento de paginación
• expand: Matriz: campos adicionales para incluir (["description", "lead", "issueTypes", "url", "projectKeys"])

Ejemplos:

# Get all projects
jira_get_projects

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

Parámetros de tableros

La herramienta jira_get_boards admite la gestión de tableros:

Parámetros opcionales:

• maxResults: Número (1-100, predeterminado: 50): limita el número de resultados
• startAt: Número (predeterminado: 0): desplazamiento de paginación
• type: Cadena: tipo de tablero ("scrum", "kanban")
• name: Cadena: filtrar por nombre del tablero
• projectKeyOrId: Cadena: filtrar por proyecto

Ejemplos:

# 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

La herramienta jira_get_sprints admite la gestión de sprints:

Obligatorios:

• boardId: Número: ID del tablero del que obtener los sprints

Parámetros opcionales:

• maxResults: Número (1-100, predeterminado: 50): limita el número de resultados
• startAt: Número (predeterminado: 0): desplazamiento de paginación
• state: Cadena: estado del sprint ("active", "closed", "future")

Ejemplos:

# 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 registros de trabajo

Las herramientas de registro de trabajo admiten un seguimiento de tiempo integral:

Parámetros de jira_add_worklog:

Obligatorios:

• issueKey: Cadena: clave de incidencia (p. ej., "PROJ-123")
• timeSpent: Cadena: tiempo dedicado en formato JIRA (p. ej., "2h", "1d 4h", "30m")

Opcionales:

• comment: Cadena: comentario que describe el trabajo realizado
• started: Cadena: cuándo comenzó el trabajo (formato de fecha ISO, predeterminado: ahora)
• visibility: Objeto: configuraciones de visibilidad ({type: "group", value: "jira-developers"})

Parámetros de jira_get_worklogs:

Obligatorios:

• issueKey: Cadena: clave de incidencia (p. ej., "PROJ-123")

Opcionales:

• startedAfter: Cadena: filtrar registros de trabajo iniciados después de esta fecha (formato ISO)
• startedBefore: Cadena: filtrar registros de trabajo iniciados antes de esta fecha (formato ISO)

Parámetros de jira_update_worklog:

Obligatorios:

• issueKey: Cadena: clave de incidencia (p. ej., "PROJ-123")
• worklogId: Cadena: ID del registro de trabajo a actualizar

Opcionales (cualquier combinación):

• timeSpent: Cadena: actualizar el tiempo dedicado
• comment: Cadena: actualizar el comentario
• started: Cadena: actualizar la hora de inicio

Parámetros de jira_delete_worklog:

Obligatorios:

• issueKey: Cadena: clave de incidencia (p. ej., "PROJ-123")
• worklogId: Cadena: ID del registro de trabajo a eliminar

Ejemplos:

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

La herramienta jira_get_issue_comments admite divulgación progresiva con estos parámetros:

Obligatorios:

• issueKey: Cadena: clave de incidencia (p. ej., "PROJ-123")

Opciones básicas:

• maxComments: Número (1-100, predeterminado: 10): número máximo de comentarios a recuperar
• orderBy: Cadena ("created" o "updated", predeterminado: "created"): orden de clasificación de los comentarios

Opciones avanzadas:

• includeInternal: Booleano (predeterminado: false) - Incluir comentarios internos/restringidos
• authorFilter: Cadena - Filtrar comentarios por nombre de autor o correo electrónico
• dateRange: Objeto - Filtrar por rango de fechas:
  • from: Cadena (fecha ISO) - Fecha de inicio
  • to: Cadena (fecha ISO) - Fecha de fin

Ejemplos:

# 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 búsqueda

La herramienta search_jira_issues admite dos modos:

Modo experto (JQL):

• jql: Cadena de consulta JQL directa (p. ej., "project = PROJ AND status = Open")

Modo principiante (parámetros auxiliares):

• assignedToMe: Booleano - Mostrar solo problemas asignados al usuario actual
• project: Cadena - Filtrar por clave de proyecto
• status: Cadena o matriz - Filtrar por estado(s) (p. ej., "Open" o ["Open", "In Progress"])
• text: Cadena - Buscar en los campos de resumen y descripción

Opciones comunes:

• maxResults: Número (1-50, predeterminado: 25) - Limitar número de resultados
• fields: Matriz - Especificar qué campos recuperar (opcional)

🛠️ Herramientas de desarrollo

Herramientas de calidad de código

El proyecto utiliza Biome para el formateo y linting de código, lo que proporciona:

• Formateo y linting unificados y rápidos
• Herramientas centradas en TypeScript
• Cero configuración necesaria
• Aplicación consistente del 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

Integración con Claude Desktop

🔌 Integración con el IDE Cursor

⚠️ Importante: Debes compilar el proyecto con bun run build antes de integrarlo con el IDE Cursor o Claude Desktop.

Añade este servidor MCP a la configuración MCP de tu IDE Cursor:

{
  "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"
      }
    }
  }
}

📁 Estructura del proyecto

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

📝 Contribuciones

¡Agradecemos las contribuciones! Consulta nuestra Guía de contribución para obtener detalles sobre:

• Flujo de trabajo de desarrollo
• Estrategia de ramas
• Formato de mensajes de confirmación
• Proceso de solicitudes de extracción
• Directrices de estilo de código

📘 Recursos

• Documentación del Protocolo de Contexto de Modelo
• SDK de TypeScript de MCP
• Especificación de MCP
• MCP Inspector
• Documentación de la API REST de JIRA

📄 Licencia

MIT © Stanislav Stepanenko