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

Clonar el repositorio:
git clone https://github.com/aaronsb/jira-insights-mcp.git cd jira-insights-mcp
Instalar dependencias:
npm install
Construir el proyecto:
npm run build

Estibador

Construya la imagen de Docker:

./scripts/build-local.sh

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:

{
  "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 utilizar la imagen de Docker (recomendada para la mayoría de los usuarios), utilice 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 de GitHub Container Registry y la ejecuta con las variables de entorno necesarias.

Corriendo localmente por el 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

administrar_esquema_jira_insight

Administre esquemas de objetos de Jira Insights con operaciones CRUD.

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

administrar_tipo_de_objeto_de_jira_insight

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

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

objeto de gestión de Jira Insight

Administre 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 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

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

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
Biblioteca de consultas de ejemplo
- Consultas de ejemplo específicas del esquema
- Sugerencias de consultas sensibles al contexto
- Plantillas de consulta para operaciones comunes
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

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
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
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)

Jira Insights MCP

Integrations

Jira Insights MCP

Descripción general

Características

Prerrequisitos

Instalación

Desarrollo local

Estibador

Uso

Configuración de MCP

Configuración de compilación local

Configuración basada en Docker

Corriendo localmente por el desarrollo

Herramientas disponibles

administrar_esquema_jira_insight

administrar_tipo_de_objeto_de_jira_insight

objeto de gestión de Jira Insight

Recursos disponibles

Mejoras planificadas

Mejoras de alta prioridad

Mejoras de prioridad media

Desarrollo

Guiones

Scripts de Docker

Solución de problemas

Problemas comunes

Licencia

Tools