Jira MCP Server

Um servidor MCP para acessar dados de issues do JIRA armazenados no Snowflake.

GitHub
9
Experimente este MCPPatrocinado

Documentação

Jira MCP Server

Um servidor Model Context Protocol (MCP) que fornece acesso aos dados de issues do JIRA armazenados no Snowflake. Este servidor permite que assistentes de IA consultem, filtrem e analisem issues do JIRA por meio de uma interface padronizada.

Visão Geral

Este servidor MCP conecta-se ao Snowflake para consultar dados do JIRA e fornece cinco ferramentas principais para interagir com os dados:

  • list_jira_issues - Consulta e filtra issues do JIRA com diversos critérios
  • get_jira_issue_details - Obtém informações detalhadas de múltiplas issues por suas chaves
  • get_jira_project_summary - Obtém estatísticas e resumos de todos os projetos
  • get_jira_issue_links - Obtém links de issue para uma issue específica do JIRA pela sua chave
  • get_jira_issues_by_sprint - Obtém todas as issues do JIRA em um sprint específico pelo nome do sprint

Recursos

Fontes de Dados

O servidor conecta-se ao Snowflake e consulta as seguintes tabelas:

  • JIRA_ISSUE_NON_PII - Dados principais das issues (informações não pessoalmente identificáveis)
  • JIRA_LABEL_RHAI - Rótulos e tags das issues
  • JIRA_COMMENT_NON_PII - Comentários das issues (informações não pessoalmente identificáveis)
  • JIRA_COMPONENT_RHAI - Componentes dos projetos do JIRA e seus metadados
  • JIRA_NODEASSOCIATION_RHAI - Associações entre entidades do JIRA (issues, componentes, versões)
  • JIRA_PROJECTVERSION_NON_PII - Versões dos projetos (versões corrigidas e versões afetadas)
  • JIRA_ISSUELINK_RHAI - Links entre issues do JIRA
  • JIRA_ISSUELINKTYPE_RHAI - Tipos de links de issue
  • JIRA_CUSTOMFIELDVALUE_NON_PII - Valores de campos personalizados (ex.: informações de sprint)
  • JIRA_SPRINT_RHAI - Dados de sprint
  • JIRA_CHANGEGROUP_RHAI - Grupos de histórico de alterações
  • JIRA_CHANGEITEM_RHAI - Itens de alteração individuais (ex.: mudanças de status)

Nota: Espera-se que os nomes das tabelas existam no banco de dados e schema do Snowflake configurados.

Ferramentas Disponíveis

1. Listar Issues (list_jira_issues)

Consulte issues do JIRA com filtragem opcional:

  • Filtro por projeto - Filtre pela chave do projeto (ex.: 'SMQE', 'OSIM')
  • Filtro por chaves de issue - Filtre por chaves de issue específicas (ex.: ['SMQE-1280', 'SMQE-1281'])
  • Filtro por tipo de issue - Filtre pelo ID do tipo de issue
  • Filtro por status - Filtre pelo ID do status da issue
  • Filtro por prioridade - Filtre pelo ID da prioridade
  • Busca por texto - Pesquise nos campos de resumo e descrição
  • Filtro por componente - Filtre por nomes de componentes (separados por vírgula, corresponde a qualquer um)
  • Filtro por versão - Filtre pela versão corrigida ou pelo nome da versão afetada
  • Filtro por data - Filtre pela data de criação, atualização ou resolução nos últimos N dias
  • Filtro por período - Filtre issues em que qualquer data (criação, atualização ou resolução) esteja nos últimos N dias
  • Limite de resultados - Controle o número de resultados retornados (padrão: 50)

Retorna informações da issue, incluindo:

  • Informações básicas da issue (resumo, descrição, status, prioridade)
  • Carimbos de data/hora (criação, atualização, data de vencimento, data de resolução)
  • Metadados (votos, observadores, ambiente, componentes)
  • Rótulos e links associados
  • Versões corrigidas e afetadas

2. Obter Detalhes da Issue (get_jira_issue_details)

Recupere informações abrangentes para múltiplas issues do JIRA por suas chaves (ex.: ['SMQE-1280', 'SMQE-1281']), incluindo:

  • Informações básicas da issue (resumo, descrição, status, prioridade)
  • Carimbos de data/hora (criação, atualização, data de vencimento, data de resolução)
  • Controle de tempo (estimativa original, estimativa atual, tempo gasto)
  • Metadados (votos, observadores, ambiente, componentes, ID do fluxo de trabalho, segurança, status de arquivamento)
  • Rótulos associados
  • Comentários (com corpo do comentário, carimbos de data/hora de criação/atualização e nível de função)
  • Links de issue (entrada e saída)
  • Histórico de mudanças de status
  • Versões corrigidas e afetadas

Retorna um dicionário com:

  • found_issues - Dicionário de issues encontradas, indexado pela chave da issue
  • not_found - Lista de chaves de issue que não foram encontradas
  • total_found - Número de issues encontradas
  • total_requested - Número de issues solicitadas

3. Obter Resumo do Projeto (get_jira_project_summary)

Gere estatísticas em todos os projetos:

  • Contagem total de issues por projeto
  • Distribuição de status por projeto
  • Distribuição de prioridade por projeto
  • Estatísticas gerais

4. Obter Links de Issue (get_jira_issue_links)

Obtenha links de issue para uma issue específica do JIRA pela sua chave (ex.: 'SMQE-1280'):

  • Links de issue - Relacionamentos com outras issues (bloqueia, é bloqueado por, relaciona-se a, etc.)
  • Direção do link - Indica se o link é de entrada ou saída
  • Detalhes da issue vinculada - Informações sobre a issue vinculada

Retorna informações, incluindo:

  • Chave e ID da issue
  • Lista de todos os links de issue com tipo e direção do link
  • Contagem total de links

5. Obter Issues por Sprint (get_jira_issues_by_sprint)

Obtenha todas as issues do JIRA em um sprint específico pelo nome do sprint:

  • Filtro por sprint - Filtre pelo nome do sprint (ex.: 'Sprint 256')
  • Filtro por projeto - Filtro opcional pela chave do projeto (ex.: 'SMQE', 'OSIM')
  • Limite de resultados - Controle o número de resultados retornados (padrão: 50)

Retorna informações da issue, incluindo:

  • Todos os campos padrão da issue (mesmos de list_jira_issues)
  • ID do sprint e nome do sprint
  • Rótulos e links associados
  • Versões corrigidas e afetadas

Monitoramento e Métricas

O servidor inclui suporte opcional a métricas do Prometheus para monitoramento:

  • Rastreamento de uso de ferramentas - Rastreie chamadas a cada ferramenta MCP com taxas de sucesso/erro e duração
  • Monitoramento de consultas do Snowflake - Monitore o desempenho e as taxas de sucesso das consultas ao banco de dados
  • Rastreamento de conexões - Rastreie conexões MCP ativas
  • Endpoints HTTP - /metrics para coleta do Prometheus e /health para verificações de saúde

Pré-requisitos

  • Python 3.10+
  • UV (gerenciador de pacotes Python)
  • Podman ou Docker
  • Acesso ao Snowflake com credenciais apropriadas

Arquitetura

O código-fonte está organizado em componentes modulares no diretório src/:

  • src/mcp_server.py - Ponto de entrada principal do servidor e inicialização do MCP
  • src/config.py - Gerenciamento de configuração e manipulação de variáveis de ambiente
  • src/database.py - Conexão com o banco de dados Snowflake e execução de consultas
  • src/tools.py - Implementações das ferramentas MCP e lógica de negócios
  • src/metrics.py - Coleta opcional de métricas do Prometheus e servidor HTTP

Variáveis de Ambiente

As seguintes variáveis de ambiente são usadas para configurar a conexão com o Snowflake:

Método de Conexão

  • SNOWFLAKE_CONNECTION_METHOD - Método de conexão a ser usado
    • Valores: api (API REST) ou connector (snowflake-connector-python)
    • Padrão: api

Método da API REST (Padrão)

Ao usar SNOWFLAKE_CONNECTION_METHOD=api:

Obrigatório

  • SNOWFLAKE_TOKEN - Seu token de autenticação do Snowflake (token Bearer)
  • SNOWFLAKE_BASE_URL - URL base da API do Snowflake (ex.: https://your-account.snowflakecomputing.com/api/v2)
  • SNOWFLAKE_DATABASE - Nome do banco de dados do Snowflake que contém seus dados do JIRA
  • SNOWFLAKE_SCHEMA - Nome do schema do Snowflake que contém suas tabelas do JIRA

Método do Conector (Suporte a Conta de Serviço)

Ao usar SNOWFLAKE_CONNECTION_METHOD=connector:

Obrigatório para Todos os Métodos

  • SNOWFLAKE_ACCOUNT - Identificador da conta do Snowflake (ex.: your-account.snowflakecomputing.com)
  • SNOWFLAKE_DATABASE - Nome do banco de dados do Snowflake que contém seus dados do JIRA
  • SNOWFLAKE_SCHEMA - Nome do schema do Snowflake que contém suas tabelas do JIRA
  • SNOWFLAKE_WAREHOUSE - Nome do warehouse do Snowflake

Métodos de Autenticação

Autenticação por Chave Privada (Recomendada para Contas de Serviço)

  • SNOWFLAKE_AUTHENTICATOR - Defina como snowflake_jwt
  • SNOWFLAKE_USER - Nome de usuário do Snowflake que possui a chave pública registrada
  • SNOWFLAKE_PRIVATE_KEY_FILE - Caminho para o arquivo de chave privada (formato PKCS#8)
  • SNOWFLAKE_PRIVATE_KEY_FILE_PWD - Senha da chave privada (opcional, se a chave estiver criptografada)

Autenticação por Nome de Usuário/Senha

  • SNOWFLAKE_AUTHENTICATOR - Defina como snowflake (padrão)
  • SNOWFLAKE_USER - Nome de usuário do Snowflake
  • SNOWFLAKE_PASSWORD - Senha do Snowflake

Credenciais de Cliente OAuth

  • SNOWFLAKE_AUTHENTICATOR - Defina como oauth_client_credentials
  • SNOWFLAKE_OAUTH_CLIENT_ID - ID do cliente OAuth
  • SNOWFLAKE_OAUTH_CLIENT_SECRET - Segredo do cliente OAuth
  • SNOWFLAKE_OAUTH_TOKEN_URL - URL do token OAuth (opcional)

Token OAuth

  • SNOWFLAKE_AUTHENTICATOR - Defina como oauth
  • SNOWFLAKE_TOKEN - Token de acesso OAuth

Opcional

  • SNOWFLAKE_ROLE - Função do Snowflake a ser usada (opcional)

Configuração Geral

  • MCP_TRANSPORT - Protocolo de transporte para comunicação MCP
    • Padrão: stdio
  • ENABLE_METRICS - Habilite a coleta de métricas do Prometheus
    • Padrão: false
  • METRICS_PORT - Porta para o servidor HTTP de métricas
    • Padrão: 8000

Exemplo de Configuração de Chave Privada

Para configurar a autenticação por chave privada:

  1. Gere o par de chaves RSA:

    # Generate private key
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8

# Generate public key
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub

  2. Registre a chave pública no usuário do Snowflake:

    ALTER USER your_service_account SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...';

  3. Defina as variáveis de ambiente:

    export SNOWFLAKE_CONNECTION_METHOD=connector
export SNOWFLAKE_AUTHENTICATOR=snowflake_jwt
export SNOWFLAKE_ACCOUNT=your-account.snowflakecomputing.com
export SNOWFLAKE_USER=your_service_account
export SNOWFLAKE_PRIVATE_KEY_FILE=/path/to/rsa_key.p8
export SNOWFLAKE_DATABASE=your_database
export SNOWFLAKE_SCHEMA=your_schema
export SNOWFLAKE_WAREHOUSE=your_warehouse
export SNOWFLAKE_ROLE=your_role

Instalação e Configuração

Migração de pip para UV

Este projeto foi atualizado para usar UV para gerenciamento de dependências. Se você já possui uma configuração existente:

  1. Remova seu ambiente virtual antigo:

    rm -rf venv/

  2. Instale o UV se ainda não o fez (consulte a seção Desenvolvimento Local abaixo)

  3. Instale as dependências com UV:

    uv sync

Desenvolvimento Local

  1. Clone o repositório:
git clone <repository-url>
cd jira-mcp-snowflake
  1. Instale o UV se ainda não o fez:
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv
  1. Instale as dependências:
uv sync

  1. Configure as variáveis de ambiente (consulte a seção Variáveis de Ambiente acima)

  2. Execute o servidor:

uv run python src/mcp_server.py

Usando Alvos do Makefile

Para conveniência, vários alvos do Makefile estão disponíveis para agilizar tarefas de desenvolvimento:

Configuração de Desenvolvimento

# Install dependencies including dev packages
make uv_sync_dev

Testes e Garantia de Qualidade

# Run linting (flake8)
make lint

# Run tests with coverage
make pytest

# Run both linting and tests
make test

Compilação

# Build container image with Podman
make build

Nota: No macOS, talvez seja necessário instalar uma versão mais recente do make via Homebrew:

brew install make

Implantação em Contêiner

Compilando localmente

Para compilar a imagem do contêiner localmente usando Podman, execute:

podman build -t localhost/jira-mcp-snowflake:latest .

Isso criará uma imagem local chamada jira-mcp-snowflake:latest que você pode usar para executar o servidor. O contêiner agora usa UV para gerenciamento rápido de dependências.

Executando com Podman ou Docker

Exemplo 1: API REST com Token

{
  "mcpServers": {
    "jira-mcp-snowflake": {
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "SNOWFLAKE_CONNECTION_METHOD=api",
        "-e", "SNOWFLAKE_TOKEN=your_token_here",
        "-e", "SNOWFLAKE_BASE_URL=https://your-account.snowflakecomputing.com/api/v2",
        "-e", "SNOWFLAKE_DATABASE=your_database_name",
        "-e", "SNOWFLAKE_SCHEMA=your_schema_name",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "ENABLE_METRICS=true",
        "-e", "METRICS_PORT=8000",
        "localhost/jira-mcp-snowflake:latest"
      ]
    }
  }
}

Exemplo 2: Autenticação por Chave Privada (Conta de Serviço)

{
  "mcpServers": {
    "jira-mcp-snowflake": {
      "command": "podman",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/path/to/your/rsa_key.p8:/app/rsa_key.p8:ro",
        "-e", "SNOWFLAKE_CONNECTION_METHOD=connector",
        "-e", "SNOWFLAKE_AUTHENTICATOR=snowflake_jwt",
        "-e", "SNOWFLAKE_ACCOUNT=your-account.snowflakecomputing.com",
        "-e", "SNOWFLAKE_USER=your_service_account",
        "-e", "SNOWFLAKE_PRIVATE_KEY_FILE=/app/rsa_key.p8",
        "-e", "SNOWFLAKE_DATABASE=your_database_name",
        "-e", "SNOWFLAKE_SCHEMA=your_schema_name",
        "-e", "SNOWFLAKE_WAREHOUSE=your_warehouse_name",
        "-e", "SNOWFLAKE_ROLE=your_role_name",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "ENABLE_METRICS=true",
        "-e", "METRICS_PORT=8000",
        "localhost/jira-mcp-snowflake:latest"
      ]
    }
  }
}

Em seguida, acesse as métricas em: http://localhost:8000/metrics

Conectando a uma instância remota

Exemplo de configuração para conectar a uma instância remota:

{
  "mcpServers": {
    "jira-mcp-snowflake": {
      "url": "https://jira-mcp-snowflake.example.com/sse",
      "headers": {
        "X-Snowflake-Token": "your_token_here"
      }
    }
  }
}

Integração com VS Code Continue

Exemplo de configuração para adicionar ao VS Code Continue:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "jira-mcp-snowflake",
        "transport": {
          "type": "stdio",
          "command": "podman",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e", "SNOWFLAKE_TOKEN=your_token_here",
            "-e", "SNOWFLAKE_BASE_URL=https://your-account.snowflakecomputing.com/api/v2",
            "-e", "SNOWFLAKE_DATABASE=your_database_name",
            "-e", "SNOWFLAKE_SCHEMA=your_schema_name",
            "-e", "MCP_TRANSPORT=stdio",
            "-e", "ENABLE_METRICS=true",
            "-e", "METRICS_PORT=8000",
            "localhost/jira-mcp-snowflake:latest"
          ]
        }
      }
    ]
  }
}

Exemplos de Uso

Consultar Issues por Projeto

# List all issues from the SMQE project
result = await list_jira_issues(project="SMQE", limit=10)

Pesquisar Issues por Texto

# Search for issues containing "authentication" in summary or description
result = await list_jira_issues(search_text="authentication", limit=20)

Filtrar Issues por Componente

# Find issues in specific components
result = await list_jira_issues(components="Security,Authentication", limit=20)

Filtrar Issues por Versão

# Find issues with a specific fixed version
result = await list_jira_issues(fixed_version="2.5.0", limit=20)

Filtrar Issues por Data

# Find issues created in the last 7 days
result = await list_jira_issues(created_days=7, limit=20)

# Find issues updated in the last 30 days
result = await list_jira_issues(updated_days=30, limit=50)

Obter Detalhes de uma Issue Específica

# Get detailed information for multiple issues
result = await get_jira_issue_details(issue_keys=["SMQE-1280", "SMQE-1281"])

# Access the results
for issue_key, issue_data in result["found_issues"].items():
    print(f"Issue: {issue_key}")
    print(f"Summary: {issue_data['summary']}")
    print(f"Status: {issue_data['status']}")
    print(f"Labels: {issue_data['labels']}")
    print(f"Comments: {len(issue_data['comments'])}")

Obter Links de Issue

# Get all issue links for a specific issue
result = await get_jira_issue_links(issue_key="SMQE-1280")

# Access the links
print(f"Total links: {result['total_links']}")
for link in result['links']:
    print(f"Link type: {link['link_type']}")
    print(f"Direction: {link['direction']}")
    print(f"Linked issue: {link['linked_issue_key']}")

Obter Issues por Sprint

# Get all issues in a specific sprint
result = await get_jira_issues_by_sprint(sprint_name="Sprint 256", limit=50)

# Get issues in a sprint for a specific project
result = await get_jira_issues_by_sprint(
    sprint_name="Sprint 256",
    project="SMQE",
    limit=50
)

# Access the results
print(f"Sprint: {result['sprint_name']}")
print(f"Total issues: {result['total_returned']}")
for issue in result['issues']:
    print(f"Issue: {issue['key']} - {issue['summary']}")
    print(f"Status: {issue['status']}")

Obter Visão Geral do Projeto

# Get statistics for all projects
result = await get_jira_project_summary()

Monitoramento

Quando as métricas estão habilitadas, o servidor fornece os seguintes endpoints de monitoramento:

  • /metrics - Endpoint de métricas do Prometheus para coleta
  • /health - Endpoint de verificação de saúde que retorna status em JSON

Métricas Disponíveis

  • mcp_tool_calls_total - Contador de chamadas de ferramentas por nome e status da ferramenta
  • mcp_tool_call_duration_seconds - Histograma das durações das chamadas de ferramentas
  • mcp_active_connections - Medidor de conexões MCP ativas
  • mcp_snowflake_queries_total - Contador de consultas do Snowflake por status
  • mcp_snowflake_query_duration_seconds - Histograma das durações das consultas do Snowflake

Privacidade de Dados

Este servidor foi projetado para trabalhar apenas com dados não pessoalmente identificáveis (não-PII). As tabelas do Snowflake devem conter dados sanitizados, com qualquer informação pessoal sensível removida.

Considerações de Segurança

  • Variáveis de Ambiente: Armazene informações sensíveis como SNOWFLAKE_TOKEN em variáveis de ambiente, nunca no código
  • Segurança do Token: Garanta que seu token do Snowflake seja mantido seguro e rotacionado regularmente
  • Segurança de Rede: Use endpoints HTTPS e conexões de rede seguras
  • Controle de Acesso: Siga o princípio do menor privilégio para acesso ao banco de dados do Snowflake
  • Prevenção de Injeção de SQL: O servidor inclui sanitização de entrada para prevenir ataques de injeção de SQL

Dependências

  • httpx - Biblioteca cliente HTTP para comunicação com a API do Snowflake
  • fastmcp - Framework rápido de servidor MCP
  • prometheus_client - Cliente de métricas Prometheus (opcional, para monitoramento)

Desenvolvimento

Estrutura do Código

O projeto segue uma arquitetura modular:

jira-mcp-snowflake/
├── src/
│   ├── mcp_server.py      # Main entry point
│   ├── config.py          # Configuration and environment variables
│   ├── database.py        # Snowflake database operations
│   ├── tools.py           # MCP tool implementations
│   └── metrics.py         # Prometheus metrics (optional)
├── requirements.txt       # Python dependencies
└── README.md             # This file

Adicionando Novas Ferramentas

Para adicionar novas ferramentas MCP:

  1. Adicione a função da ferramenta em src/tools.py
  2. Decore com @mcp.tool() e @track_tool_usage("tool_name")
  3. Siga os padrões existentes para tratamento de erros e registro de logs
  4. Atualize este README com a documentação da nova ferramenta