Jira Insights MCP

Gestiona esquemas de activos de Jira Service Management (JSM) utilizando la API de Jira Insights.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Jira Insights MCP

Un servidor de Model Context Protocol (MCP) para gestionar esquemas de activos de Jira Insights (JSM).

Última actualización: 2025-04-09

Descripción general

Este servidor MCP proporciona herramientas para interactuar con los esquemas de activos de Jira Insights (JSM) a través del Model Context Protocol. Permite gestionar esquemas de objetos, tipos de objetos y objetos en Jira Insights.

Características

  • Gestionar esquemas de objetos (crear, leer, actualizar, eliminar)
  • Gestionar tipos de objetos (crear, leer, actualizar, eliminar)
  • Gestionar objetos (crear, leer, actualizar, eliminar)
  • Consultar objetos usando AQL (Atlassian Query Language)

Requisitos previos

  • Node.js 20 o posterior
  • Docker (para implementación en contenedores)
  • Instancia de Jira Insights con acceso a la API
  • Token de API de Jira con los permisos adecuados

Instalación

Desarrollo local

  1. Clonar el repositorio:

    git clone https://github.com/aaronsb/jira-insights-mcp.git
cd jira-insights-mcp

  2. Instalar dependencias:

    npm install

  3. Compilar el proyecto:

    npm run build

Docker

Compilar la imagen de Docker:

./scripts/build-local.sh

Uso

Configuración de MCP

Para usar este servidor MCP con Claude u otros asistentes de IA que admitan el Model Context Protocol, agréguelo a su configuración de MCP usando uno de los siguientes métodos:

Configuración de compilación local

Si ha compilado el proyecto localmente, use esta configuración:

{
  "mcpServers": {
    "jira-insights": {
      "command": "node",
      "args": ["/path/to/jira-insights-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "LOG_MODE": "strict"
      }
    }
  }
}

Configuración basada en Docker

Si prefiere usar la imagen de Docker (recomendado para la mayoría de los usuarios), use esta configuración:

{
  "mcpServers": {
    "jira-insights": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_API_TOKEN",
        "-e", "JIRA_EMAIL",
        "-e", "JIRA_HOST",
        "ghcr.io/aaronsb/jira-insights-mcp:latest"
      ],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_HOST": "https://your-domain.atlassian.net"
      }
    }
  }
}

Esta configuración basada en Docker extrae la última imagen del GitHub Container Registry y la ejecuta con las variables de entorno necesarias.

Ejecución local para desarrollo

Para desarrollo y pruebas locales:

# Build the Docker image
./scripts/build-local.sh

# Run the Docker container
JIRA_API_TOKEN=your_token JIRA_EMAIL=your_email JIRA_HOST=your_host ./scripts/run-local.sh

Herramientas disponibles

manage_jira_insight_schema

Gestionar esquemas de objetos de Jira Insights con operaciones CRUD.

{
  "operation": "list",
  "maxResults": 10
}

manage_jira_insight_object_type

Gestionar tipos de objetos de Jira Insights con operaciones CRUD.

{
  "operation": "list",
  "schemaId": "1",
  "maxResults": 20
}

manage_jira_insight_object

Gestionar objetos de Jira Insights con operaciones CRUD y consultas AQL.

{
  "operation": "query",
  "aql": "objectType = \"Application\"",
  "maxResults": 10
}

Recursos disponibles

El servidor MCP proporciona varios recursos para acceder a los datos de Jira Insights:

  • jira-insights://instance/summary - Estadísticas de alto nivel sobre la instancia de Jira Insights
  • jira-insights://aql-syntax - Guía completa de la sintaxis de Assets Query Language (AQL) con ejemplos
  • jira-insights://schemas/all - Lista completa de todos los esquemas con sus tipos de objetos
  • jira-insights://schemas/{schemaId}/full - Definición completa de un esquema específico, incluidos los tipos de objetos
  • jira-insights://schemas/{schemaId}/overview - Resumen de un esquema específico, incluidos metadatos y estadísticas
  • jira-insights://object-types/{objectTypeId}/overview - Resumen de un tipo de objeto específico, incluidos atributos y estadísticas

Mejoras planificadas

Estamos trabajando en varias mejoras para potenciar la funcionalidad y usabilidad del Jira Insights MCP:

Mejoras de alta prioridad

  1. Manejo mejorado de errores

    • Mensajes de error más detallados con problemas de validación específicos
    • Correcciones sugeridas para errores comunes
    • Ejemplos específicos de operaciones para ayudar a los usuarios a corregir problemas

  2. Mejoras en consultas AQL

    • Utilidades de validación y formato para consultas AQL
    • Consultas de ejemplo específicas del esquema
    • Mejores mensajes de error para problemas de consulta

  3. Mejora en el descubrimiento de atributos

    • Recuperación mejorada de atributos para tipos de objetos
    • Caché para un mejor rendimiento
    • Mejor manejo del parámetro "expand"

Mejoras de prioridad media

  1. Generación de plantillas de objetos

    • Plantillas para crear objetos basadas en tipos de objetos
    • Generación de marcadores de posición específicos del tipo
    • Reglas de validación en plantillas

  2. Biblioteca de consultas de ejemplo

    • Consultas de ejemplo específicas del esquema
    • Sugerencias de consultas sensibles al contexto
    • Plantillas de consulta para operaciones comunes

  3. Documentación mejorada

    • Documentación mejorada de la sintaxis de AQL
    • Documentación específica de operaciones
    • Escenarios de error comunes y soluciones

Para más detalles sobre las mejoras planificadas, consulte:

  • TODO.md - Lista de tareas completa con todas las tareas organizadas por prioridad
  • IMPLEMENTATION_PLAN.md - Planes de implementación detallados para las mejoras de alta prioridad
  • HANDLER_IMPROVEMENTS.md - Cambios específicos necesarios para cada archivo de controlador
  • IMPROVEMENT_SUMMARY.md - Resumen conciso de las mejoras planificadas
  • docs/API_MIGRATION_TODO.md - Estado de la migración de la API y las mejoras planificadas

Desarrollo

Scripts

  • npm run build: Compilar el código TypeScript
  • npm run lint: Ejecutar ESLint
  • npm run lint:fix: Ejecutar ESLint con corrección automática
  • npm run test: Ejecutar pruebas
  • npm run watch: Observar cambios y recompilar
  • npm run generate-diagrams: Generar diagramas de dependencias de TypeScript

Scripts de Docker

  • ./scripts/build-local.sh: Compilar la imagen de Docker
  • ./scripts/run-local.sh: Ejecutar el contenedor de Docker

Solución de problemas

Problemas comunes

  1. Errores de validación de consultas AQL

    • Asegúrese de que los valores con espacios estén entre comillas: Name = "John Doe"
    • Use mayúsculas para los operadores lógicos: AND, OR (no and, or)
    • Verifique que los tipos de objetos y atributos existan en su esquema

  2. Problemas con atributos de tipos de objetos

    • Al usar el parámetro "expand" con "attributes", asegúrese de que el tipo de objeto exista
    • Verifique que tenga permisos para ver los atributos

  3. Problemas de conexión con la API

    • Verifique que su token de API de Jira tenga los permisos necesarios
    • Compruebe que la URL del host de Jira sea correcta
    • Asegúrese de que su red permita conexiones a la API de Jira

Licencia

MIT