Jira

Integra con la API REST de Jira para gestionar proyectos, rastrear incidencias y realizar análisis.

GitHub
8
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Jira

smithery badge

Un servidor integral del Protocolo de Contexto de Modelos que proporciona integración a nivel empresarial con la API REST de Jira, permitiendo a los asistentes de IA realizar gestión avanzada de proyectos, análisis y tareas de planificación estratégica.

Nota: Este es un fork mantenido de 1broseidon/mcp-jira-server. Agradecemos el trabajo original y continuamos desarrollando y mejorando este proyecto de forma independiente. Todo el crédito por la implementación inicial corresponde a los autores originales.

🚀 Descripción General de Funcionalidades

Este servidor transforma la funcionalidad básica de Jira en una plataforma completa de gestión de proyectos con concurrencia y seguridad de hilos a nivel empresarial:

🔒 Concurrencia Empresarial y Seguridad de Hilos

  • Soporte Multi-Cliente Seguro para Hilos: Múltiples sesiones de Claude Code pueden usar el mismo servidor simultáneamente de forma segura
  • Aislamiento de Estado Basado en Sesiones: Cada conexión de cliente obtiene su propio estado de sesión aislado
  • Caché de Configuración por Sesión: Previene condiciones de carrera y mejora el rendimiento
  • Gestión Automática de Sesiones: Tiempo de espera de sesión de 30 minutos con limpieza gradual
  • Arquitectura Lista para Producción: Diseñada para entornos empresariales de alta concurrencia

Gestión de Incidencias Principal

  • Crear, actualizar, eliminar y gestionar incidencias de Jira
  • Consulta avanzada de incidencias con soporte JQL
  • Puntos de historia y gestión de sprints
  • Vinculación de épicas y gestión de jerarquías
  • Manejo de comentarios y archivos adjuntos
  • 🆕 Soporte de Seguimiento de Tiempo: Seguimiento de tiempo nativo con campos original_estimate y remaining_estimate
  • 🆕 Transiciones de Flujo de Trabajo: Gestión completa del flujo de trabajo con herramientas de transición
  • Soporte Multi-instancia: Trabaje con múltiples entornos de Jira Cloud desde una sola sesión

🏗️ Estructura y Organización de Proyectos

  • Gestión de Componentes: Organice el trabajo por áreas de funcionalidad y equipos
  • Seguimiento de Versiones/Lanzamientos: Gestione hitos de lanzamiento y progreso
  • Descubrimiento de Proyectos: Busque y analice proyectos en toda su instancia de Jira
  • Análisis de Configuración: Comprenda la configuración del proyecto y optimice los flujos de trabajo

📊 Análisis Avanzado e Información

  • Seguimiento de Progreso: Progreso de componentes y versiones con indicadores visuales
  • Análisis de Flujo de Trabajo: Comprenda las transiciones de estado y los cuellos de botella
  • Rendimiento del Equipo: Distribución de carga de trabajo de los asignados y seguimiento de actividad
  • Planificación Estratégica: Hoja de ruta de alto nivel y gestión de planes

🔍 Consultas Avanzadas y Automatización

  • Búsqueda JQL: Ejecute consultas complejas con análisis integral
  • Filtros Guardados: Cree consultas reutilizables con permisos de uso compartido
  • Búsqueda Entre Proyectos: Descubra y analice proyectos en toda la organización
  • Operaciones Masivas: Gestione eficientemente múltiples incidencias y proyectos

📋 Referencia Completa de Herramientas

Herramientas de Gestión de Incidencias

create_issue

Crea nuevas incidencias de Jira con soporte integral de campos

  • Parámetros: resumen, descripción, tipo, enlace_épica, prioridad, puntos_historia, etiquetas, sprint, claveProyecto
  • Funcionalidades: Detecta automáticamente los campos de puntos de historia, soporta asignación de sprints

list_issues

Lista las incidencias del proyecto con opciones de filtrado y ordenamiento

  • Parámetros: estado, clave_épica, campoOrden, ordenOrden, claveProyecto
  • Funcionalidades: Separadores visuales, visualización de información de sprint, ordenamiento basado en rango

update_issue

Actualiza incidencias existentes con soporte completo de campos, incluido el seguimiento de tiempo

  • Parámetros: clave_incidencia, resumen, descripción, estado, asignado, enlace_épica, prioridad, puntos_historia, etiquetas, sprint, rango_después_incidencia, rango_antes_incidencia, estimación_original, estimación_restante, campos_personalizados, claveProyecto
  • Funcionalidades: Clasificación de incidencias, gestión de sprints, vinculación de épicas, resolución inteligente de asignados, soporte de seguimiento de tiempo, manejo dinámico de campos de componentes

get_issue

Recupera información detallada de incidencias

  • Parámetros: clave_incidencia
  • Funcionalidades: Metadatos completos de incidencias, comentarios, relaciones

delete_issue

Elimina de forma segura incidencias de los proyectos

  • Parámetros: clave_incidencia

add_comment

Agrega comentarios a incidencias existentes

  • Parámetros: clave_incidencia, comentario

get_transitions 🆕 v1.1.0

Obtenga las transiciones de flujo de trabajo disponibles para una incidencia

  • Parámetros: clave_incidencia, directorio_trabajo, instancia (opcional)
  • Funcionalidades: Lista las transiciones disponibles, campos requeridos e IDs de transición
  • Caso de Uso: Comprenda las opciones de flujo de trabajo antes de realizar transiciones

transition_issue 🆕 v1.1.0

Realice transiciones de flujo de trabajo en incidencias (por ejemplo, mover a "En Progreso", "Hecho")

  • Parámetros: clave_incidencia, id_transición O nombre_transición, comentario (opcional), resolución (opcional), campos (opcional), directorio_trabajo, instancia (opcional)
  • Funcionalidades: Transición por nombre o ID, configuración automática de resolución, adición de comentarios
  • Caso de Uso: Automatice cambios de estado y progresión del flujo de trabajo

list_custom_fields 🆕 v1.1.0

Descubra los campos personalizados disponibles para la configuración

  • Parámetros: directorio_trabajo, instancia (opcional), claveProyecto (opcional), mostrarCamposSistema (opcional)
  • Funcionalidades: Descubrimiento de campos, ejemplos de configuración, clasificación de tipos
  • Caso de Uso: Incorporación de nuevos usuarios, configuración de campos, exploración del sistema

⚙️ Gestión de Configuración e Instancias

list_instances

Lista las instancias de Jira disponibles y sus configuraciones

  • Funcionalidades: Descubrimiento de instancias, mapeos de proyectos, guía de configuración, validación de configuración
  • Casos de Uso: Verificación de configuración multi-instancia, solución de problemas, planificación de configuración

🏗️ Herramientas de Estructura de Proyectos

create_component

Crea componentes de proyectos basados en funcionalidades

  • Parámetros: nombre, descripción, idCuentaLíder, tipoAsignado
  • Funcionalidades: Asignación de líder, enrutamiento automático de incidencias

list_components

Lista todos los componentes del proyecto con detalles

  • Funcionalidades: Categorización de componentes, información del líder, estadísticas de uso

get_component_progress

Análisis integral de componentes y seguimiento de progreso

  • Funcionalidades: Porcentajes de progreso, desgloses de estado, análisis de actividad reciente, distribución de carga de trabajo

create_version

Crea versiones de proyecto para la gestión de lanzamientos

  • Parámetros: nombre, descripción, fechaInicio, fechaLanzamiento, lanzado, archivado
  • Funcionalidades: Gestión de cronograma de lanzamientos, seguimiento de hitos

list_versions

Lista las versiones del proyecto con categorización

  • Funcionalidades: Separación activa/lanzada/archivada, información de cronograma, advertencias de retraso

get_version_progress

Análisis detallado del progreso y cronograma de versiones

  • Funcionalidades: Seguimiento de finalización, desgloses de incidencias, monitoreo de plazos, información del cronograma

🔍 Herramientas de Consulta Avanzada

search_issues_jql

Ejecute consultas JQL avanzadas con análisis integral

  • Parámetros: jql, maxResultados, iniciarEn, campos, expandir, validarConsulta
  • Funcionalidades: Validación de consultas, análisis de resultados, paginación, optimización de rendimiento

search_projects

Descubra y busque proyectos en toda la organización

  • Parámetros: consulta, tipoClave, idCategoría, estado, maxResultados, iniciarEn, expandir
  • Funcionalidades: Descubrimiento entre proyectos, análisis de metadatos, categorización

create_filter

Cree filtros guardados para un seguimiento consistente

  • Parámetros: nombre, jql, descripción, favorito, permisosCompartidos
  • Funcionalidades: Gestión de permisos, colaboración en equipo, reutilización de consultas

📊 Herramientas de Análisis de Proyectos

get_project_details

Información integral del proyecto y análisis de estructura

  • Parámetros: claveProyecto, expandir
  • Funcionalidades: Metadatos completos, resúmenes de componentes/versiones, análisis de permisos

get_project_statuses

Análisis de configuración de flujo de trabajo y estados

  • Funcionalidades: Categorización de estados, información de optimización de flujo de trabajo, mapeo de transiciones

get_issue_types

Descubrimiento de tipos de incidencias y análisis de configuración

  • Funcionalidades: Jerarquía de tipos, requisitos de campos, pautas de uso

detect_project_fields

🆕 Descubrimiento de Configuración de Campos - Esencial para la incorporación de nuevos usuarios

  • Parámetros: directorio_trabajo, claveProyecto, instancia (opcional)
  • Propósito: Detectar automáticamente los IDs de campos personalizados requeridos para la configuración del proyecto
  • Salida: Fragmentos de configuración listos para copiar para .jira-config.json
  • Detecta: IDs de campos de Puntos de Historia, Sprint y Enlace de Épica utilizando heurísticas inteligentes
  • Multi-Instancia: Soporte completo para múltiples entornos de Jira
  • Consciente de Sesión: Proporciona orientación solo en el primer acceso al proyecto por sesión
  • Caso de Uso: Elimina la búsqueda manual de IDs de campos en la interfaz de administración de Jira

🌉 Herramientas de Integración Entre Servidores

jira_health_check

🆕 Monitoreo de Salud del Servidor - Monitoree el estado del servidor de Jira y la integración entre servidores

  • Propósito: Verifique la salud del servidor, el tiempo de actividad y la conectividad entre servidores
  • Salida: Estado de salud integral, detalles de configuración, operaciones compatibles
  • Entre Servidores: Muestra el estado de integración con los servidores MCP de Confluence
  • Información de Sesión: Conteo de sesiones en tiempo real y monitoreo de actividad

confluence_health_check

🆕 Verificación de Salud Entre Servidores - Monitoree la conectividad del servidor de Confluence desde Jira

  • Propósito: Verifique el estado de integración Jira-a-Confluence y las capacidades
  • Salida: Estado de conexión, verificación de endpoints, configuración de integración

🎯 Herramientas de Planificación Estratégica

list_plans

Gestión de planes estratégicos (funcionalidad de Jira Premium)

  • Funcionalidades: Seguimiento de hoja de ruta de alto nivel, análisis de cronograma, métricas de equipo

Herramientas de Gestión de Sprints y Épicas

create_sprint

Crea nuevos sprints con objetivos y cronogramas

  • Parámetros: nombre, objetivo, fechaInicio, fechaFin, idTablero, claveProyecto

update_sprint

Modifica los detalles y el cronograma de sprints existentes

  • Parámetros: idSprint, nombre, objetivo, fechaInicio, fechaFin, estado

get_sprint_details

Progreso integral de sprints y análisis

  • Funcionalidades: Seguimiento de incidencias, información de velocidad, datos de burndown

move_issues_to_sprint

Asignación masiva de sprints para incidencias

  • Parámetros: idSprint, clavesIncidencia

complete_sprint

Cierra sprints activos y maneja el trabajo restante

  • Parámetros: idSprint

create_epic

Crea nuevas épicas para la organización de grandes funcionalidades

  • Parámetros: nombre, resumen, descripción, prioridad, etiquetas, claveProyecto

create_epic_with_issues

Crea una épica con incidencias vinculadas en una sola operación ⚡

  • Parámetros: épica (nombre, resumen, descripción, prioridad, etiquetas), incidencias (matriz de datos de incidencias)
  • Funcionalidades: Reduce las llamadas a la API, asegura el vinculado adecuado, manejo integral de errores
  • Beneficios: Operación atómica, valida todos los tipos de incidencias, resolución automática de asignados

update_epic_details

Actualiza las propiedades y el estado de las épicas

  • Parámetros: claveÉpica, nombre, resumen, color, hecho

rank_epics y rank_issues

Gestiona la priorización de épicas e incidencias

  • Funcionalidades: Clasificación relativa, gestión de prioridades

bulk_update_issues

Actualiza eficientemente múltiples incidencias simultáneamente

  • Parámetros: clavesIncidencia, actualizaciones (estado, asignado, etiquetas, prioridad, sprint, puntosHistoria)
  • Funcionalidades: Operaciones masivas, manejo de errores por incidencia, resolución inteligente de asignados

Herramientas de Tableros e Informes

list_boards

Lista los tableros Kanban y Scrum disponibles

  • Funcionalidades: Categorización de tableros, asociación de proyectos

get_board_configuration

Analiza la configuración del tablero y la configuración de columnas

  • Funcionalidades: Mapeo de flujo de trabajo, análisis de columnas

get_sprint_report, get_velocity_chart_data, get_burndown_chart_data

Análisis avanzado de sprints y rendimiento del equipo

  • Funcionalidades: Seguimiento de velocidad, análisis de burndown, información de rendimiento

🛠️ Configuración e Instalación

Requisitos Previos

  1. Cuenta de Jira: Con acceso a la API y permisos apropiados
  2. Token de API: Generado desde Configuración de la Cuenta de Atlassian
  3. Acceso al Proyecto: Permisos de lectura/escritura para los proyectos objetivo

Instalación

Instalación mediante npm

npm install -g jira-server

Después de la instalación, el comando jira-server estará disponible globalmente.

Instalación mediante Smithery

Para instalar Jira Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install jira-server --client claude

Instalación Manual

  1. Instalar dependencias:
# Clone and install dependencies
npm install

# Build the server
npm run build

Configuración

1. Configuración Multi-Instancia (Recomendado)

El Servidor MCP de Jira soporta múltiples instancias de Jira desde una única sesión de Claude Desktop. Esto permite cambiar sin problemas entre diferentes entornos de Jira Cloud según las claves de proyecto.

Crea .jira-config.json en tu directorio de trabajo:

{
  "instances": {
    "primary": {
      "email": "your-email@company.com",
      "apiToken": "your-api-token-here",
      "domain": "your-domain",
      "projects": ["PROJ", "DEV", "OPS"]
    },
    "secondary": {
      "email": "your-email@otherdomain.com", 
      "apiToken": "your-other-api-token",
      "domain": "other-domain"
    }
  },
  "projects": {
    "PROJ": {
      "instance": "primary",
      "storyPointsField": "customfield_10016",
      "sprintField": "customfield_10020",
      "epicLinkField": "customfield_10014"
    },
    "DEV": {
      "instance": "primary",
      "storyPointsField": "customfield_10016"
    },
    "OTHER": {
      "instance": "secondary",
      "storyPointsField": "customfield_10020"
    }
  },
  "defaultInstance": "primary"
}

Lógica de Selección de Instancia

El servidor selecciona automáticamente la instancia de Jira correcta usando este orden de prioridad:

  1. Anulación Explícita: Parámetro manual instance en las llamadas de herramientas
  2. Mapeo de Proyectos: Configuración directa de proyecto a instancia en la sección projects
  3. Listas de Proyectos de Instancia: Proyectos listados en los arreglos projects de la instancia
  4. Instancia Predeterminada: Recurso a la configuración defaultInstance
  5. Instancia Única: Usar la única instancia disponible si solo hay una configurada

2. Configuración Heredada de Instancia Única (Aún Soportada)

Para configuraciones de una sola instancia de Jira, usa el formato simplificado:

{
  "projectKey": "YOUR_PROJECT_KEY",
  "storyPointsField": "customfield_XXXXX",  // Optional: auto-detected
  "sprintField": "customfield_YYYYY",       // Optional: auto-detected  
  "epicLinkField": "customfield_ZZZZZ"      // Optional: auto-detected
}

3. Configuración del Servidor MCP

Para Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-server/build/index.js"],
      "cwd": "/path/to/jira-server",
      "env": {
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token", 
        "JIRA_DOMAIN": "your-domain"
      },
      "disabled": false,
      "alwaysAllow": true
    }
  }
}

Para la Extensión Cline de VS Code (~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-server/build/index.js"],
      "cwd": "/path/to/jira-server", 
      "env": {
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DOMAIN": "your-domain"
      },
      "disabled": false,
      "alwaysAllow": [
        "create_issue", "list_issues", "update_issue", "get_issue", "delete_issue", "add_comment",
        "list_instances", "create_component", "list_components", "get_component_progress",
        "create_version", "list_versions", "get_version_progress", 
        "search_issues_jql", "search_projects", "create_filter",
        "get_project_details", "get_project_statuses", "get_issue_types",
        "list_plans", "create_sprint", "update_sprint", "get_sprint_details",
        "create_epic", "update_epic_details", "bulk_update_issues"
      ]
    }
  }
}

Para OpenCode (opencode.json en el proyecto o ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "local",
      "command": ["node", "build/index.js"],
      "enabled": true,
      "environment": {
        "JIRA_CONFIG_PATH": "./config/.jira-config.json"
      }
    }
  }
}

JIRA_CONFIG_PATH puede ser absoluta, relativa al archivo de configuración, o usar ~ para el directorio de inicio. Si registras el servidor bajo un nombre MCP diferente, establece JIRA_MCP_KEY a ese valor para que el cargador pueda ubicar el bloque correcto.

4. Configuración de Integración Entre Servidores

Para la integración entre servidores de los servidores MCP de Jira y Confluence, necesitarás instalar y configurar el servidor complementario confluence-cloud-mcp junto con este servidor de Jira.

Agrega la configuración de API de Confluence a tu .jira-config.json:

{
  "instances": {
    "primary": {
      "email": "your-email@company.com",
      "apiToken": "your-jira-api-token",
      "domain": "your-jira-domain",
      "projects": ["PROJ", "DEV"]
    }
  },
  "confluence": {
    "instances": {
      "primary": {
        "email": "your-email@company.com",
        "apiToken": "your-confluence-api-token",
        "domain": "your-confluence-domain"
      }
    },
    "defaultInstance": "primary"
  },
  "defaultInstance": "primary"
}

Esto habilita herramientas como jira_health_check, confluence_health_check y capacidades de creación de documentos entre servidores.

Beneficios de la Integración Entre Servidores:

  • Enlace Bidireccional: Crea enlaces inteligentes entre incidencias de Jira y páginas de Confluence
  • Documentación Automatizada: Genera páginas de Confluence directamente desde incidencias de Jira (épicas, funcionalidades, etc.)
  • Monitoreo de Salud: Supervisa ambos servidores y su estado de integración
  • Flujo de Trabajo Unificado: Cambia sin problemas entre el seguimiento de incidencias y la documentación dentro de la misma sesión de IA

Para instrucciones completas de configuración y funciones avanzadas entre servidores, consulta la documentación de confluence-cloud-mcp.

🎯 Ejemplos de Uso

Gestión Multi-Instancia

Descubrimiento de Instancias

// List all configured instances and project mappings
await list_instances({ working_dir: "/path/to/config" });

Selección Automática de Instancia

// Automatically uses correct instance based on project key
await create_issue({
  working_dir: "/path/to/config",
  projectKey: "HWY",  // Routes to Highway instance
  summary: "New feature request",
  description: "Implement user dashboard",
  type: "Task"
});

await create_issue({
  working_dir: "/path/to/config", 
  projectKey: "ONVX", // Routes to Onvex instance
  summary: "Security update",
  description: "Update authentication system",
  type: "Task"
});

Anulación Manual de Instancia

// Explicitly specify instance for any tool call
await create_issue({
  working_dir: "/path/to/config",
  instance: "highway",  // Force use of Highway instance
  projectKey: "PROJ",
  summary: "Cross-instance task",
  type: "Task"
});

Flujo de Trabajo de Planificación de Proyectos

// 1. Analyze project structure
await get_project_details({ projectKey: "PROJ" });

// 2. Create components for feature organization  
await create_component({
  name: "Authentication API",
  description: "User authentication and authorization features",
  leadAccountId: "user123"
});

// 3. Create release version
await create_version({
  name: "v2.0.0", 
  description: "Major feature release",
  releaseDate: "2024-06-30"
});

// 4. Search for related work
await search_issues_jql({
  jql: "project = PROJ AND component = 'Authentication API' AND fixVersion = 'v2.0.0'"
});

Seguimiento de Progreso y Analíticas

// Component progress analysis
await get_component_progress({ componentId: "10123" });

// Version release tracking  
await get_version_progress({ versionId: "10456" });

// Sprint performance metrics
await get_sprint_report({ boardId: 1, sprintId: 23 });

Consultas Avanzadas y Automatización

// Create saved filter for team tracking
await create_filter({
  name: "Backend Team Sprint Work",
  jql: "assignee in (dev1, dev2, dev3) AND sprint in openSprints()",
  sharePermissions: [{ type: "project", projectId: "10000" }]
});

// Bulk update for sprint planning
await bulk_update_issues({
  issueKeys: ["PROJ-1", "PROJ-2", "PROJ-3"],
  updates: { sprint: "Sprint 5", storyPoints: 3 }
});

🆕 Gestión de Seguimiento de Tiempo y Flujos de Trabajo (v1.1.0)

Ejemplos de Seguimiento de Tiempo

// Set time estimates on issue creation
await create_issue({
  working_dir: "/path/to/config",
  projectKey: "PROJ",
  summary: "Implement user authentication",
  description: "Build OAuth2 integration",
  type: "Task",
  story_points: 5,
  original_estimate: "2w",  // 2 weeks
  // Time automatically displayed in get_issue
});

// Update time tracking on existing issues
await update_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123",
  original_estimate: "1w 2d",     // 1 week 2 days
  remaining_estimate: "3d 4h"     // 3 days 4 hours
});

// Use with component assignment
await update_issue({
  working_dir: "/path/to/config", 
  issue_key: "PROJ-124",
  custom_fields: {
    "Component": "Security"  // Automatically converts to [{name: "Security"}]
  },
  original_estimate: "5d"
});

Ejemplos de Transición de Flujo de Trabajo

// Discover available transitions for an issue
await get_transitions({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123"
});

// Transition issue to "In Progress" with comment
await transition_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123",
  transition_name: "Start Progress",  // or transition_id: "21"
  comment: "Beginning work on this issue"
});

// Complete issue with resolution
await transition_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123", 
  transition_name: "Done",
  comment: "Implementation completed and tested",
  resolution: "Fixed"
});

// Workflow automation - bulk transition
const issueKeys = ["PROJ-101", "PROJ-102", "PROJ-103"];
for (const key of issueKeys) {
  await transition_issue({
    working_dir: "/path/to/config",
    issue_key: key,
    transition_name: "Ready for Review"
  });
}

Ejemplos de Descubrimiento de Campos

// Discover all available fields for configuration
await list_custom_fields({
  working_dir: "/path/to/config",
  instance: "primary",
  projectKey: "PROJ",  // Optional: project-specific fields
  showSystemFields: false  // Show only custom fields
});

// Get ready-to-copy configuration snippets
// Output includes examples like:
// - Story Points: customfield_10036
// - Sprint: customfield_10020  
// - Components: Built-in system field

Épica con Incidencias - Creación Masiva ⚡

La nueva herramienta create_epic_with_issues te permite crear una épica y múltiples incidencias vinculadas en una sola operación:

// Create epic with linked issues in one operation
await create_epic_with_issues({
  working_dir: "/path/to/config",
  projectKey: "PROJ",
  epic: {
    name: "User Authentication System",
    summary: "Complete user authentication and authorization",
    description: "Implement secure user authentication with OAuth2 and role-based access control",
    priority: "High",
    labels: ["security", "authentication"]
  },
  issues: [
    {
      summary: "Design OAuth2 integration",
      description: "Research and design OAuth2 flow for user authentication",
      type: "Task",
      story_points: 5,
      assignee: "john.doe@company.com",
      priority: "High"
    },
    {
      summary: "Implement user registration API",
      description: "Create REST API endpoints for user registration",
      type: "Story",
      story_points: 8,
      assignee: "Jane Smith",
      labels: ["api", "backend"]
    },
    {
      summary: "Build login form UI",
      description: "Create responsive login form with validation",
      type: "Task", 
      story_points: 3,
      assignee: "mike.wilson@company.com",
      priority: "Medium"
    }
  ]
});

Beneficios de la Creación Masiva:

  • Menos Llamadas de API: Una sola operación en lugar de múltiples llamadas separadas
  • Vinculación Automática: Todas las incidencias se vinculan automáticamente a la épica
  • Operación Atómica: O todos los elementos se crean correctamente o ninguno
  • Validación Integral: Valida la épica y todas las incidencias antes de la creación
  • Manejo de Errores Mejorado: Retroalimentación detallada sobre cualquier fallo de validación
  • Resolución Inteligente de Asignados: Resuelve automáticamente nombres de usuario/correos electrónicos a IDs de cuenta

Ejemplos de Gestión de Asignados

El Servidor MCP de Jira proporciona resolución inteligente de asignados que acepta nombres para mostrar, correos electrónicos o IDs de cuenta y los resuelve automáticamente a la cuenta de Jira correcta.

Asignación de Incidencias Individuales

// Assign by display name (most common)
await update_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123",
  assignee: "Esther Yang"  // Resolves to account ID automatically
});

// Assign by email address
await update_issue({
  working_dir: "/path/to/config", 
  issue_key: "PROJ-124",
  assignee: "esther.yang@company.com"
});

// Unassign issue
await update_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-125", 
  assignee: "unassigned"  // or null, or empty string
});

Operaciones de Asignación Masiva

// Assign multiple issues to one person
await bulk_update_issues({
  working_dir: "/path/to/config",
  issueKeys: ["PROJ-101", "PROJ-102", "PROJ-103"],
  updates: {
    assignee: "Rob Sherman",  // Intelligent name resolution
    sprint: "Sprint 10"
  }
});

// Unassign multiple issues
await bulk_update_issues({
  working_dir: "/path/to/config",
  issueKeys: ["PROJ-201", "PROJ-202"],
  updates: {
    assignee: "unassigned"
  }
});

Lógica de Resolución de Asignados

El sistema maneja automáticamente la resolución de usuarios usando este orden de prioridad:

  1. Coincidencia Exacta de Nombre para Mostrar: "Esther Yang" → Coincidencia exacta en usuarios de Jira
  2. Coincidencia de Dirección de Correo: "esther.yang@company.com" → Coincidencia por correo electrónico
  3. Coincidencia Parcial de Nombre: "Esther" → Se encontró una sola coincidencia parcial
  4. Paso Directo de ID de Cuenta: Si ya es un ID de cuenta, se usa tal cual

Manejo de Errores:

  • Sin Coincidencia Encontrada: Mensaje de error claro con nombres similares sugeridos
  • Múltiples Coincidencias: Lista todas las posibilidades y solicita más especificidad
  • Usuarios Inválidos: Valida que el usuario exista y esté activo

Valores Especiales:

  • "unassigned", null o "" → Desasigna la incidencia
  • Los IDs de cuenta que comienzan con patrones específicos se usan directamente

🔧 Funciones Avanzadas

Detección Inteligente de Campos

  • Detecta automáticamente campos personalizados (Puntos de Historia, Sprint, Enlace de Épica)
  • Proporciona orientación de configuración en los registros de depuración
  • Soporta anulación manual de ID de campo

Operaciones Entre Proyectos

  • Busca y gestiona incidencias en múltiples proyectos
  • Capacidades de descubrimiento y análisis de proyectos
  • Informes y perspectivas a nivel organizacional

Optimización de Rendimiento

  • Operaciones por lotes eficientes para actualizaciones masivas
  • Soporte de paginación para conjuntos de datos grandes
  • Validación de consultas y sugerencias de optimización

Analíticas e Informes Enriquecidos

  • Indicadores visuales de progreso y porcentajes
  • Análisis de cronogramas con seguimiento de plazos
  • Rendimiento del equipo y distribución de carga de trabajo
  • Análisis de tendencias históricas y perspectivas

🐛 Solución de Problemas

Registro de Depuración

Supervisa la actividad del servidor con registros detallados:

# For Claude Desktop (macOS)
tail -f ~/Library/Logs/Claude/mcp-server-jira.log

# For development
npm run watch  # Auto-rebuild on changes

Problemas Comunes

Problemas de Detección de Campos

  • Usuarios Nuevos: Usa la herramienta detect_project_fields para descubrir automáticamente los IDs de campos
  • Campos Faltantes: Las herramientas ahora proporcionan orientación automática en el primer acceso al proyecto por sesión
  • Revisa los registros de depuración para ver mensajes "Se encontró el campo [Campo]"
  • Verifica los IDs de campos personalizados en la administración del proyecto
  • Asegura los permisos de campo adecuados

Rendimiento de Consultas

  • Usa validateQuery: true para probar JQL
  • Implementa paginación para conjuntos de resultados grandes
  • Supervisa la complejidad de las consultas en los registros de depuración

Problemas de Configuración

  • El servidor verifica múltiples ubicaciones de configuración en orden:
    1. Parámetro del directorio de trabajo (working_dir)
    2. Directorio de trabajo actual (process.cwd())
    3. Directorio de instalación del servidor
  • Verifica el formato y los permisos de .jira-config.json

Problemas de Configuración Multi-Instancia

  • Instancia No Encontrada: Usa list_instances para verificar los nombres y configuraciones de las instancias
  • Instancia Incorrecta Seleccionada: Revisa los mapeos de proyectos en la sección projects y los arreglos projects de la instancia
  • Fallos de Autenticación: Verifica que cada instancia tenga el correo electrónico, apiToken y dominio correctos
  • Conflictos de Claves de Proyecto: Asegura que las claves de proyecto sean únicas entre instancias o estén mapeadas correctamente
  • Validación de Configuración: Usa list_instances para verificar la configuración y obtener orientación para la solución de problemas

Límites de Velocidad de la API

  • Implementa retrasos entre operaciones masivas
  • Usa operaciones por lotes cuando estén disponibles
  • Supervisa los encabezados de respuesta de la API para conocer el estado del límite de velocidad

Mensajes de Error Mejorados 🎯

El servidor ahora proporciona mensajes de error detallados y fáciles de usar con orientación específica para la solución de problemas:

Errores de Validación de Campos

  • Problemas de Campos Detallados: Explicaciones claras para cada problema de campo
  • Nombres Fáciles de Usar: Los IDs de campos técnicos se convierten en nombres legibles (por ejemplo, customfield_10011 → Epic Name)
  • Orientación Específica por Campo: Consejos dirigidos para problemas de campos comunes

Solución de Problemas Contextual

  • Problemas de Permisos: Pasos específicos para resolver problemas de acceso
  • Problemas de Configuración: Orientación para la configuración de campos y proyectos
  • Fallos de Validación: Explicación clara de qué salió mal y cómo solucionarlo

Ejemplo de Error Mejorado

# Invalid Request: epic creation failed

The request contains invalid data or violates Jira field requirements.

## Field Issues
- **Epic Name:** Field 'customfield_10011' is not supported for issue type 'Epic' in this project
- **Priority:** Priority 'Critical' is not available. Available priorities: Highest, High, Medium, Low, Lowest

## Troubleshooting Steps
1. Epic Name field may not be available in this project
2. Try creating the epic without the Epic Name field  
3. Check available priorities for this project
4. Common values: Highest, High, Medium, Low, Lowest

Códigos de Error y Resolución

Tipo de ErrorCausas ComunesResolución
401 UnauthorizedToken de API o correo electrónico inválidoVerifica las credenciales en la configuración de MCP
403 ForbiddenPermisos de proyecto insuficientesRevisa los roles y permisos del proyecto en Jira
404 Not FoundClave de proyecto o clave de incidencia inválidaVerifica que el proyecto/incidencia exista y sea accesible
400 Bad RequestValores de campo o transiciones inválidosMejorado: Validación de campos detallada con orientación específica

🚀 Desarrollo

Configuración de Desarrollo

# Install dependencies
npm install

# Development with auto-rebuild  
npm run watch

# Run tests
npm test

# Build for production
npm run build

Pruebas

El proyecto incluye pruebas Jest integrales con soporte para ESM y TypeScript:

# Run all tests
npm test

# Run tests in watch mode during development
npm run test:watch

# Generate test coverage report
npm run test:coverage

Estructura de Pruebas:

  • tests/unit/ - Pruebas unitarias para módulos individuales (configuración, formato, conversión ADF)
  • tests/integration/ - Pruebas de integración para la funcionalidad del servidor
  • Usa Jest con ts-jest para soporte de ESM en TypeScript
  • Las pruebas se ejecutan automáticamente en el pipeline de CI/CD

Características Clave:

  • Pruebas de módulos ESM con importaciones de extensión .js
  • Compilación de TypeScript mediante ts-jest
  • Módulos VM experimentales de Node.js para compatibilidad con ESM
  • Cobertura integral para utilidades y funcionalidad principal

Contribuciones

  1. Detección de Campos: Agrega soporte para nuevos campos personalizados en src/config/config.ts
  2. Desarrollo de Herramientas: Sigue los patrones existentes en src/tools/
  3. Extensiones de API: Extiende el cliente base en src/jira-client.ts
  4. Pruebas: Agrega pruebas integrales para la nueva funcionalidad

📈 Funciones Empresariales

Integración de Planificación Estratégica

  • Vincula el trabajo táctico con iniciativas estratégicas
  • Informes y perspectivas a nivel de portafolio
  • Seguimiento de dependencias entre proyectos

Analíticas Avanzadas

  • Métricas personalizadas y seguimiento de KPIs
  • Evaluación comparativa del rendimiento del equipo
  • Pronóstico predictivo de entregas

Optimización de Flujos de Trabajo

  • Identificación y resolución de cuellos de botella
  • Recomendaciones de mejora de procesos
  • Descubrimiento de oportunidades de automatización

Seguridad y Cumplimiento

  • Registro de auditoría y seguimiento de cambios
  • Análisis y optimización de permisos
  • Gobernanza de datos e informes de cumplimiento

Transforma tu experiencia con Jira desde el seguimiento básico de incidencias hasta una plataforma integral de gestión de proyectos y planificación estratégica.