Jira Insights MCP

Gerencie esquemas de ativos do Jira Service Management (JSM) usando a API Jira Insights.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Jira Insights MCP

Um servidor Model Context Protocol (MCP) para gerenciar esquemas de ativos do Jira Insights (JSM).

Última atualização: 2025-04-09

Visão Geral

Este servidor MCP fornece ferramentas para interagir com esquemas de ativos do Jira Insights (JSM) por meio do Model Context Protocol. Ele permite gerenciar esquemas de objetos, tipos de objetos e objetos no Jira Insights.

Recursos

  • Gerenciar esquemas de objetos (criar, ler, atualizar, excluir)
  • Gerenciar tipos de objetos (criar, ler, atualizar, excluir)
  • Gerenciar objetos (criar, ler, atualizar, excluir)
  • Consultar objetos usando AQL (Atlassian Query Language)

Pré-requisitos

  • Node.js 20 ou posterior
  • Docker (para implantação em contêiner)
  • Instância do Jira Insights com acesso à API
  • Token de API do Jira com permissões adequadas

Instalação

Desenvolvimento Local

  1. Clone o repositório:

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

  2. Instale as dependências:

    npm install

  3. Compile o projeto:

    npm run build

Docker

Compile a imagem Docker:

./scripts/build-local.sh

Uso

Configuração do MCP

Para usar este servidor MCP com o Claude ou outros assistentes de IA que suportam o Model Context Protocol, adicione-o à sua configuração MCP usando um dos seguintes métodos:

Configuração de Build Local

Se você compilou o projeto localmente, use esta configuração:

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

Configuração Baseada em Docker

Se você preferir usar a imagem Docker (recomendado para a maioria dos usuários), use esta configuração:

{
  "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 configuração baseada em Docker baixa a imagem mais recente do GitHub Container Registry e a executa com as variáveis de ambiente necessárias.

Executando Localmente para Desenvolvimento

Para desenvolvimento e testes locais:

# 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

Ferramentas Disponíveis

manage_jira_insight_schema

Gerencie esquemas de objetos do Jira Insights com operações CRUD.

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

manage_jira_insight_object_type

Gerencie tipos de objetos do Jira Insights com operações CRUD.

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

manage_jira_insight_object

Gerencie objetos do Jira Insights com operações CRUD e consultas AQL.

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

Recursos Disponíveis

O servidor MCP fornece vários recursos para acessar dados do Jira Insights:

  • jira-insights://instance/summary - Estatísticas de alto nível sobre a instância do Jira Insights
  • jira-insights://aql-syntax - Guia abrangente sobre a sintaxe da Assets Query Language (AQL) com exemplos
  • jira-insights://schemas/all - Lista completa de todos os esquemas com seus tipos de objetos
  • jira-insights://schemas/{schemaId}/full - Definição completa de um esquema específico, incluindo tipos de objetos
  • jira-insights://schemas/{schemaId}/overview - Visão geral de um esquema específico, incluindo metadados e estatísticas
  • jira-insights://object-types/{objectTypeId}/overview - Visão geral de um tipo de objeto específico, incluindo atributos e estatísticas

Melhorias Planejadas

Estamos trabalhando em várias melhorias para aprimorar a funcionalidade e a usabilidade do Jira Insights MCP:

Melhorias de Alta Prioridade

  1. Tratamento de Erros Aprimorado

    • Mensagens de erro mais detalhadas com problemas específicos de validação
    • Correções sugeridas para erros comuns
    • Exemplos específicos de operações para ajudar os usuários a corrigir problemas

  2. Melhorias nas Consultas AQL

    • Utilitários de validação e formatação para consultas AQL
    • Consultas de exemplo específicas do esquema
    • Melhores mensagens de erro para problemas de consulta

  3. Aprimoramento da Descoberta de Atributos

    • Recuperação aprimorada de atributos para tipos de objetos
    • Cache para melhor desempenho
    • Melhor tratamento do parâmetro "expand"

Melhorias de Prioridade Média

  1. Geração de Modelos de Objetos

    • Modelos para criar objetos com base em tipos de objetos
    • Geração de espaços reservados específicos do tipo
    • Regras de validação em modelos

  2. Biblioteca de Consultas de Exemplo

    • Consultas de exemplo específicas do esquema
    • Sugestões de consultas sensíveis ao contexto
    • Modelos de consulta para operações comuns

  3. Documentação Aprimorada

    • Documentação aprimorada da sintaxe AQL
    • Documentação específica de operações
    • Cenários de erro comuns e soluções

Para mais detalhes sobre as melhorias planejadas, consulte:

  • TODO.md - Lista de tarefas abrangente com todas as tarefas organizadas por prioridade
  • IMPLEMENTATION_PLAN.md - Planos de implementação detalhados para as melhorias de alta prioridade
  • HANDLER_IMPROVEMENTS.md - Alterações específicas necessárias para cada arquivo de handler
  • IMPROVEMENT_SUMMARY.md - Resumo conciso das melhorias planejadas
  • docs/API_MIGRATION_TODO.md - Status da migração da API e das melhorias planejadas

Desenvolvimento

Scripts

  • npm run build: Compilar o código TypeScript
  • npm run lint: Executar o ESLint
  • npm run lint:fix: Executar o ESLint com correção automática
  • npm run test: Executar os testes
  • npm run watch: Observar alterações e recompilar
  • npm run generate-diagrams: Gerar diagramas de dependência do TypeScript

Scripts Docker

  • ./scripts/build-local.sh: Compilar a imagem Docker
  • ./scripts/run-local.sh: Executar o contêiner Docker

Solução de Problemas

Problemas Comuns

  1. Erros de Validação de Consultas AQL

    • Certifique-se de que valores com espaços estejam entre aspas: Name = "John Doe"
    • Use letras maiúsculas para operadores lógicos: AND, OR (não and, or)
    • Verifique se os tipos de objetos e atributos existem no seu esquema

  2. Problemas com Atributos de Tipos de Objetos

    • Ao usar o parâmetro "expand" com "attributes", certifique-se de que o tipo de objeto exista
    • Verifique se você tem permissões para visualizar os atributos

  3. Problemas de Conexão com a API

    • Verifique se o token da API do Jira tem as permissões necessárias
    • Verifique se a URL do host do Jira está correta
    • Certifique-se de que sua rede permite conexões com a API do Jira

Licença

MIT