Servidor MCP de Jira

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso a los datos de incidencias de JIRA almacenados en Snowflake. Este servidor permite a los asistentes de IA consultar, filtrar y analizar incidencias de JIRA a través de una interfaz estandarizada.

Descripción general

Este servidor MCP se conecta a Snowflake para consultar datos de JIRA y proporciona cinco herramientas principales para interactuar con los datos:

list_jira_issues - Consultar y filtrar incidencias de JIRA con varios criterios
get_jira_issue_details - Obtener información detallada de múltiples incidencias por sus claves
get_jira_project_summary - Obtener estadísticas y resúmenes de todos los proyectos
get_jira_issue_links - Obtener enlaces de incidencias para una incidencia de JIRA específica por su clave
get_jira_issues_by_sprint - Obtener todas las incidencias de JIRA en un sprint específico por nombre del sprint

Características

Fuentes de datos

El servidor se conecta a Snowflake y consulta las siguientes tablas:

JIRA_ISSUE_NON_PII - Datos principales de incidencias (información no personalmente identificable)
JIRA_LABEL_RHAI - Etiquetas y marcas de incidencias
JIRA_COMMENT_NON_PII - Comentarios de incidencias (información no personalmente identificable)
JIRA_COMPONENT_RHAI - Componentes de proyectos JIRA y sus metadatos
JIRA_NODEASSOCIATION_RHAI - Asociaciones entre entidades de JIRA (incidencias, componentes, versiones)
JIRA_PROJECTVERSION_NON_PII - Versiones de proyectos (versiones de corrección y versiones afectadas)
JIRA_ISSUELINK_RHAI - Enlaces entre incidencias de JIRA
JIRA_ISSUELINKTYPE_RHAI - Tipos de enlaces de incidencias
JIRA_CUSTOMFIELDVALUE_NON_PII - Valores de campos personalizados (por ejemplo, información de sprint)
JIRA_SPRINT_RHAI - Datos de sprints
JIRA_CHANGEGROUP_RHAI - Grupos de historial de cambios
JIRA_CHANGEITEM_RHAI - Elementos de cambio individuales (por ejemplo, cambios de estado)

Nota: Se espera que los nombres de las tablas existan en la base de datos y el esquema de Snowflake configurados.

Herramientas disponibles

1. Listar Incidencias (`list_jira_issues`)

Consultar incidencias de JIRA con filtrado opcional:

Filtrado por proyecto - Filtrar por clave de proyecto (por ejemplo, 'SMQE', 'OSIM')
Filtrado por claves de incidencia - Filtrar por claves de incidencia específicas (por ejemplo, ['SMQE-1280', 'SMQE-1281'])
Filtrado por tipo de incidencia - Filtrar por ID de tipo de incidencia
Filtrado por estado - Filtrar por ID de estado de incidencia
Filtrado por prioridad - Filtrar por ID de prioridad
Búsqueda de texto - Buscar en los campos de resumen y descripción
Filtrado por componente - Filtrar por nombres de componentes (separados por comas, coincide con cualquiera)
Filtrado por versión - Filtrar por versión corregida o nombre de versión afectada
Filtrado por fecha - Filtrar por fecha de creación, actualización o resolución dentro de los últimos N días
Filtrado por período de tiempo - Filtrar incidencias donde cualquier fecha (creada, actualizada o resuelta) esté dentro de los últimos N días
Limitación de resultados - Controlar el número de resultados devueltos (predeterminado: 50)

Devuelve información de la incidencia que incluye:

Información básica de la incidencia (resumen, descripción, estado, prioridad)
Marcas de tiempo (creación, actualización, fecha de vencimiento, fecha de resolución)
Metadatos (votos, seguimientos, entorno, componentes)
Etiquetas y enlaces asociados
Versiones corregidas y afectadas

2. Obtener Detalles de Incidencia (`get_jira_issue_details`)

Recuperar información completa de múltiples incidencias de JIRA por sus claves (por ejemplo, ['SMQE-1280', 'SMQE-1281']), que incluye:

Información básica de la incidencia (resumen, descripción, estado, prioridad)
Marcas de tiempo (creación, actualización, fecha de vencimiento, fecha de resolución)
Seguimiento de tiempo (estimación original, estimación actual, tiempo invertido)
Metadatos (votos, seguimientos, entorno, componentes, ID de flujo de trabajo, seguridad, estado de archivado)
Etiquetas asociadas
Comentarios (con cuerpo del comentario, marcas de tiempo de creación/actualización y nivel de rol)
Enlaces de incidencias (entrantes y salientes)
Historial de cambios de estado
Versiones corregidas y afectadas

Devuelve un diccionario con:

found_issues - Diccionario de incidencias encontradas claveadas por clave de incidencia
not_found - Lista de claves de incidencia que no fueron encontradas
total_found - Número de incidencias encontradas
total_requested - Número de incidencias solicitadas

3. Obtener Resumen de Proyecto (`get_jira_project_summary`)

Generar estadísticas en todos los proyectos:

Conteos totales de incidencias por proyecto
Distribución de estados por proyecto
Distribución de prioridades por proyecto
Estadísticas generales

4. Obtener Enlaces de Incidencias (`get_jira_issue_links`)

Obtener enlaces de incidencias para una incidencia de JIRA específica por su clave (por ejemplo, 'SMQE-1280'):

Enlaces de incidencias - Relaciones con otras incidencias (bloquea, es bloqueado por, se relaciona con, etc.)
Dirección del enlace - Indica si el enlace es entrante o saliente
Detalles de la incidencia enlazada - Información sobre la incidencia enlazada

Devuelve información que incluye:

Clave e ID de la incidencia
Lista de todos los enlaces de incidencias con tipo de enlace y dirección
Conteo total de enlaces

5. Obtener Incidencias por Sprint (`get_jira_issues_by_sprint`)

Obtener todas las incidencias de JIRA en un sprint específico por nombre del sprint:

Filtrado por sprint - Filtrar por nombre del sprint (por ejemplo, 'Sprint 256')
Filtrado por proyecto - Filtro opcional por clave de proyecto (por ejemplo, 'SMQE', 'OSIM')
Limitación de resultados - Controlar el número de resultados devueltos (predeterminado: 50)

Devuelve información de la incidencia que incluye:

Todos los campos estándar de incidencias (igual que list_jira_issues)
ID del sprint y nombre del sprint
Etiquetas y enlaces asociados
Versiones corregidas y afectadas

Monitoreo y métricas

El servidor incluye soporte opcional de métricas de Prometheus para monitoreo:

Seguimiento de uso de herramientas - Rastrear llamadas a cada herramienta MCP con tasas de éxito/error y duración
Monitoreo de consultas de Snowflake - Monitorear el rendimiento de consultas de base de datos y tasas de éxito
Seguimiento de conexiones - Rastrear conexiones MCP activas
Puntos finales HTTP - /metrics para el scraping de Prometheus y /health para verificaciones de salud

Requisitos previos

Python 3.10+
UV (gestor de paquetes de Python)
Podman o Docker
Acceso a Snowflake con las credenciales apropiadas

Arquitectura

El código está organizado en componentes modulares en el directorio src/:

src/mcp_server.py - Punto de entrada principal del servidor e inicialización de MCP
src/config.py - Gestión de configuración y manejo de variables de entorno
src/database.py - Conexión a la base de datos Snowflake y ejecución de consultas
src/tools.py - Implementaciones de herramientas MCP y lógica de negocio
src/metrics.py - Recolección de métricas de Prometheus opcional y servidor HTTP

Variables de entorno

Las siguientes variables de entorno se utilizan para configurar la conexión a Snowflake:

Método de conexión

SNOWFLAKE_CONNECTION_METHOD - Método de conexión a utilizar
- Valores: api (API REST) o connector (snowflake-connector-python)
- Predeterminado: api

Método de API REST (Predeterminado)

Al usar SNOWFLAKE_CONNECTION_METHOD=api:

Requerido

SNOWFLAKE_TOKEN - Su token de autenticación de Snowflake (token Bearer)
SNOWFLAKE_BASE_URL - URL base de la API de Snowflake (por ejemplo, https://your-account.snowflakecomputing.com/api/v2)
SNOWFLAKE_DATABASE - Nombre de la base de datos Snowflake que contiene sus datos de JIRA
SNOWFLAKE_SCHEMA - Nombre del esquema Snowflake que contiene sus tablas de JIRA

Método de conector (soporte de cuenta de servicio)

Al usar SNOWFLAKE_CONNECTION_METHOD=connector:

Requerido para todos los métodos

SNOWFLAKE_ACCOUNT - Identificador de cuenta de Snowflake (por ejemplo, your-account.snowflakecomputing.com)
SNOWFLAKE_DATABASE - Nombre de la base de datos Snowflake que contiene sus datos de JIRA
SNOWFLAKE_SCHEMA - Nombre del esquema Snowflake que contiene sus tablas de JIRA
SNOWFLAKE_WAREHOUSE - Nombre del almacén de Snowflake

Métodos de autenticación

Autenticación con clave privada (recomendada para cuentas de servicio)

SNOWFLAKE_AUTHENTICATOR - Establecer en snowflake_jwt
SNOWFLAKE_USER - Nombre de usuario de Snowflake que tiene la clave pública registrada
SNOWFLAKE_PRIVATE_KEY_FILE - Ruta al archivo de clave privada (formato PKCS#8)
SNOWFLAKE_PRIVATE_KEY_FILE_PWD - Contraseña de la clave privada (opcional, si la clave está cifrada)

Autenticación de nombre de usuario/contraseña

SNOWFLAKE_AUTHENTICATOR - Establecer en snowflake (predeterminado)
SNOWFLAKE_USER - Nombre de usuario de Snowflake
SNOWFLAKE_PASSWORD - Contraseña de Snowflake

Credenciales de cliente OAuth

SNOWFLAKE_AUTHENTICATOR - Establecer en oauth_client_credentials
SNOWFLAKE_OAUTH_CLIENT_ID - ID de cliente OAuth
SNOWFLAKE_OAUTH_CLIENT_SECRET - Secreto de cliente OAuth
SNOWFLAKE_OAUTH_TOKEN_URL - URL de token OAuth (opcional)

Token OAuth

SNOWFLAKE_AUTHENTICATOR - Establecer en oauth
SNOWFLAKE_TOKEN - Token de acceso OAuth

Opcional

SNOWFLAKE_ROLE - Rol de Snowflake a utilizar (opcional)

Configuración general

MCP_TRANSPORT - Protocolo de transporte para comunicación MCP
- Predeterminado: stdio
ENABLE_METRICS - Habilitar la recolección de métricas de Prometheus
- Predeterminado: false
METRICS_PORT - Puerto para el servidor HTTP de métricas
- Predeterminado: 8000

Ejemplo de configuración de clave privada

Para configurar la autenticación con clave privada:

Generar par de claves 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

Registrar la clave pública con el usuario de Snowflake:

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

Establecer variables de entorno:

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

Instalación y configuración

Migración de pip a UV

Este proyecto se ha actualizado para usar UV para la gestión de dependencias. Si tiene una configuración existente:

Elimine su entorno virtual anterior:
```
rm -rf venv/
```
Instale UV si aún no lo ha hecho (consulte la sección de Desarrollo local a continuación)
Instale las dependencias con UV:
```
uv sync
```

Desarrollo local

Clone el repositorio:

git clone <repository-url>
cd jira-mcp-snowflake

Instale UV si aún no lo ha hecho:

# 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

Instale las dependencias:

uv sync

Configure las variables de entorno (consulte la sección de Variables de entorno arriba)
Ejecute el servidor:

uv run python src/mcp_server.py

Uso de objetivos de Makefile

Para mayor comodidad, hay varios objetivos de Makefile disponibles para agilizar las tareas de desarrollo:

Configuración de desarrollo

# Install dependencies including dev packages
make uv_sync_dev

Pruebas y aseguramiento de calidad

# Run linting (flake8)
make lint

# Run tests with coverage
make pytest

# Run both linting and tests
make test

Compilación

# Build container image with Podman
make build

Nota: En macOS, es posible que deba instalar una versión más nueva de make a través de Homebrew:

brew install make

Despliegue en contenedor

Compilación local

Para compilar la imagen del contenedor localmente usando Podman, ejecute:

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

Esto creará una imagen local llamada jira-mcp-snowflake:latest que puede usar para ejecutar el servidor. El contenedor ahora usa UV para una gestión rápida de dependencias.

Ejecución con Podman o Docker

Ejemplo 1: API REST con 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"
      ]
    }
  }
}

Ejemplo 2: Autenticación con clave privada (cuenta de servicio)

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

Luego acceda a las métricas en: http://localhost:8000/metrics

Conexión a una instancia remota

Ejemplo de configuración para conectarse a una instancia remota:

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

Integración con VS Code Continue

Ejemplo de configuración para agregar a 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"
          ]
        }
      }
    ]
  }
}

Ejemplos de uso

Consultar incidencias por proyecto

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

Buscar incidencias por texto

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

Filtrar incidencias por componente

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

Filtrar incidencias por versión

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

Filtrar incidencias por fecha

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

Obtener detalles de una incidencia 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'])}")

Obtener enlaces de incidencias

# 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']}")

Obtener incidencias 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']}")

Obtener resumen del proyecto

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

Monitoreo

Cuando las métricas están habilitadas, el servidor proporciona los siguientes puntos finales de monitoreo:

/metrics - Punto final de métricas de Prometheus para scraping
/health - Punto final de verificación de salud que devuelve estado JSON

Métricas disponibles

mcp_tool_calls_total - Contador de llamadas a herramientas por nombre de herramienta y estado
mcp_tool_call_duration_seconds - Histograma de duraciones de llamadas a herramientas
mcp_active_connections - Medidor de conexiones MCP activas
mcp_snowflake_queries_total - Contador de consultas de Snowflake por estado
mcp_snowflake_query_duration_seconds - Histograma de duraciones de consultas de Snowflake

Privacidad de datos

Este servidor está diseñado para trabajar solo con información no personalmente identificable (no PII). Las tablas de Snowflake deben contener datos saneados con cualquier información personal sensible eliminada.

Consideraciones de seguridad

Variables de entorno: Almacene información sensible como SNOWFLAKE_TOKEN en variables de entorno, nunca en código
Seguridad del token: Asegúrese de que su token de Snowflake se mantenga seguro y se rote regularmente
Seguridad de red: Use puntos finales HTTPS y conexiones de red seguras
Control de acceso: Siga el principio de privilegio mínimo para el acceso a la base de datos de Snowflake
Prevención de inyección SQL: El servidor incluye saneamiento de entrada para prevenir ataques de inyección SQL

Dependencias

httpx - Biblioteca cliente HTTP para la comunicación con la API de Snowflake
fastmcp - Framework de servidor MCP rápido
prometheus_client - Cliente de métricas de Prometheus (opcional, para monitoreo)

Desarrollo

Estructura del Código

El proyecto sigue una arquitectura 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

Añadir Nuevas Herramientas

Para añadir nuevas herramientas MCP:

Añade la función de la herramienta a src/tools.py
Decora con @mcp.tool() y @track_tool_usage("tool_name")
Sigue los patrones existentes para el manejo de errores y el registro
Actualiza este README con documentación para la nueva herramienta

Jira MCP Server

Documentación