Jira Insights MCP

Un servidor de Protocolo de contexto de modelo (MCP) para administrar esquemas de activos de Jira Insights (JSM).

Última actualización: 09/04/2025

Descripción general

Este servidor MCP proporciona herramientas para interactuar con los esquemas de activos de Jira Insights (JSM) mediante el Protocolo de Contexto de Modelo. Permite gestionar esquemas de objetos, tipos de objetos y objetos en Jira Insights.

Características

• Administrar esquemas de objetos (crear, leer, actualizar, eliminar)

• Administrar tipos de objetos (crear, leer, actualizar, eliminar)

• Administrar objetos (crear, leer, actualizar, eliminar)

• Consultar objetos utilizando AQL (lenguaje de consulta Atlassian)

Prerrequisitos

• 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. Construir el proyecto:

   npm run build

Estibador

Construya la imagen de Docker:

Uso

Configuración de MCP

Para utilizar este servidor MCP con Claude u otros asistentes de IA que admitan el Protocolo de contexto de modelo, agréguelo a su configuración de MCP mediante uno de los siguientes métodos:

Configuración de compilación local

Si ha creado el proyecto localmente, utilice esta configuración:

Configuración basada en Docker

Si prefiere utilizar la imagen de Docker (recomendada para la mayoría de los usuarios), utilice esta configuración:

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

Corriendo localmente por el desarrollo

Para desarrollo y pruebas locales:

Herramientas disponibles

administrar_esquema_jira_insight

Administre esquemas de objetos de Jira Insights con operaciones CRUD.

administrar_tipo_de_objeto_de_jira_insight

Administre los tipos de objetos de Jira Insights con operaciones CRUD.

objeto de gestión de Jira Insight

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

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 sobre la sintaxis del lenguaje de consulta de activos (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 : descripción general de un esquema específico que incluye metadatos y estadísticas

• jira-insights://object-types/{objectTypeId}/overview : descripción general de un tipo de objeto específico, incluidos atributos y estadísticas

Mejoras planificadas

Estamos trabajando en varias mejoras para mejorar la funcionalidad y la usabilidad de 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

   • Soluciones sugeridas para errores comunes

   • Ejemplos específicos de la operación para ayudar a los usuarios a corregir problemas

2. Mejoras en las 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 del descubrimiento de atributos

   • Recuperación de atributos mejorada para tipos de objetos

   • Almacenamiento en caché para un mejor rendimiento

   • Mejor manejo del parámetro "expandir"

Mejoras de prioridad media

1. Generación de plantillas de objetos

   • Plantillas para crear objetos basados en tipos de objetos

   • Generación de marcadores de posición específicos de cada 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 de sintaxis AQL mejorada

   • Documentación específica de la operación

   • Escenarios de error comunes y soluciones

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

• TODO.md - Lista completa de tareas por hacer 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 mejoras planificadas

Desarrollo

Guiones

• npm run build : compila el código TypeScript

• npm run lint : Ejecutar ESLint

• npm run lint:fix : Ejecuta ESLint con corrección automática

• npm run test : Ejecutar pruebas

• npm run watch : vigila los cambios y reconstruye

• npm run generate-diagrams : Genera diagramas de dependencia de TypeScript

Scripts de Docker

• ./scripts/build-local.sh : Construye la imagen de Docker

• ./scripts/run-local.sh : Ejecuta el contenedor 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"

   • Utilice mayúsculas para los operadores lógicos: AND , OR (no and , or )

   • Compruebe que los tipos de objetos y atributos existan en su esquema

2. Problemas con los atributos de tipo de objeto

   • Al utilizar el parámetro "expandir" con "atributos", asegúrese de que el tipo de objeto exista

   • Comprueba que tienes permisos para ver los atributos

3. Problemas de conexión de 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

Instituto Tecnológico de Massachusetts (MIT)