Jira Weekly Reporter

Se conecta a una instancia de Jira para generar informes semanales basados en la actividad de los issues.

Documentación

Servidor MCP de Jira Weekly Reporter

Este proyecto proporciona un servidor FastMCP que se conecta a tu instancia de Jira (Cloud o Server/Data Center) para generar informes semanales basados en la actividad de los issues. Utiliza la librería pycontribs-jira para la interacción con Jira y puede usar opcionalmente el Modelo de Lenguaje Grande (LLM) del cliente conectado para resumir el informe generado.

✨ Características

Conexión a Jira: Se conecta de forma segura a Jira usando tokens de API almacenados en un archivo .env.
Herramienta MCP: Expone una herramienta generate_jira_report accesible a través del Protocolo de Contexto de Modelo.
Informes Flexibles:
- Por defecto, informa sobre issues actualizados en los últimos 7 días.
- Permite especificar una consulta JQL personalizada.
- Puede filtrar informes por una clave de proyecto específica de Jira.
- Limita el número de resultados devueltos (configurable).
(Opcional) Resumen con LLM: Puede usar el LLM del cliente (a través de ctx.sample()) para proporcionar un resumen conciso del informe.
Manejo Asíncrono: Maneja correctamente las llamadas síncronas de la librería de Jira dentro del servidor asíncrono FastMCP usando asyncio.to_thread.

📋 Requisitos Previos

Python 3.10 o posterior.
uv (recomendado) o pip para la gestión de paquetes.
Acceso a una instancia de Jira (Cloud, Server o Data Center).
Un Token de API de Jira (Token de Acceso Personal para Server/DC).
CLI de FastMCP instalado y disponible en el PATH de tu sistema.

⚙️ Configuración

Clonar el Repositorio (si aplica):

git clone https://github.com/Jongryong/jira_reporter.git
cd jira_reporter

Instalar Dependencias: Recomendamos usar uv:

uv pip install fastmcp "jira[cli]" python-dotenv httpx anyio

Alternativamente, usa pip:

pip install fastmcp "jira[cli]" python-dotenv httpx anyio

Crear Archivo .env: Crea un archivo llamado .env en el mismo directorio que jira_reporter_server.py. Agrega los detalles de conexión de tu Jira:
```
# .env
JIRA_URL=https://your-domain.atlassian.net  # Your Jira Cloud URL or Self-Hosted URL
JIRA_USERNAME=your_email@example.com       # Your Jira login email
JIRA_API_TOKEN=your_api_token_or_pat       # Your generated API Token or PAT
```
- Seguridad:
  - ¡Nunca subas tu archivo .env al control de versiones! Agrega .env a tu archivo .gitignore.
  - Jira Cloud: Genera un token de API desde la configuración de tu cuenta de Atlassian: Gestionar tokens de API.
  - Jira Server/Data Center: Genera un Token de Acceso Personal (PAT) desde la configuración de tu perfil de usuario de Jira: Usando Tokens de Acceso Personal.

▶️ Ejecutar el Servidor (Independiente)

Puedes ejecutar el servidor de forma independiente para pruebas u otros fines:

Directamente con Python:
```
python jira_reporter_server.py
```

Usando la CLI de FastMCP:

fastmcp run jira_reporter_server.py

Para ejecutar con SSE (por ejemplo, para acceso remoto):

fastmcp run jira_reporter_server.py --transport sse --port 8001

🖥️ Uso con Claude Desktop

Para hacer que este servidor esté disponible como herramienta dentro de la aplicación Claude Desktop:

Verificar Requisitos Previos: Asegúrate de que fastmcp esté instalado y sea accesible en el PATH de tu sistema, ya que la configuración a continuación usa el comando fastmcp.
Localizar el Archivo de Configuración de Claude: Encuentra el archivo claude_desktop_config.json. Su ubicación depende de tu sistema operativo:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json (generalmente C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)
- Linux: ~/.config/Claude/claude_desktop_config.json (o $XDG_CONFIG_HOME/Claude/)
Editar el Archivo de Configuración: Abre claude_desktop_config.json en un editor de texto.
Agregar Configuración del Servidor: Encuentra el objeto "mcpServers" dentro del JSON (si no existe, créalo como un objeto vacío {}). Agrega la siguiente entrada dentro de mcpServers, asegurándote de reemplazar "path/to/your/jira_reporter_server.py" con la ruta absoluta a tu script:
```
{
  "mcpServers": {
    // ... other servers might be here ...

    "jira_report": {
      "command": "fastmcp",
      "args": [
        "run",
        "/path/to/your/jira_reporter_server.py" // <-- IMPORTANT: Use the full, absolute path here
      ]
    }

    // ... other servers might be here ...
  }
  // ... rest of your Claude config ...
}
```
- "jira_report": Este es el nombre interno que usa Claude. Puedes cambiarlo si lo deseas.
- "command": "fastmcp": Le indica a Claude que use la herramienta de línea de comandos fastmcp.
- "args": [...]: Le indica a Claude que ejecute fastmcp run /path/to/your/jira_reporter_server.py.
Guardar y Reiniciar: Guarda el archivo claude_desktop_config.json y reinicia la aplicación Claude Desktop.
Invocar la Herramienta: Ahora deberías poder usar la herramienta en Claude mencionando el nombre del servidor definido en el script de Python (Jira Weekly Reporter). Por ejemplo: @Jira Weekly Reporter generate jira report for project MYPROJ and summarize it

🛠️ Detalles de la Herramienta MCP

Nombre de la Herramienta: generate_jira_report
Descripción: Genera un informe de issues de Jira basado en una consulta JQL (por defecto, actualizados recientemente). Opcionalmente resume el informe usando el LLM del cliente.

Parámetros:

Parámetro	Tipo	Requerido	Predeterminado	Descripción
`jql_query`	`string`	No	`updated >= -7d ORDER BY updated DESC`	Consulta JQL opcional. Si se omite, se usa la predeterminada.
`project_key`	`string`	No	`None`	Clave de proyecto de Jira opcional (por ejemplo, "PROJ") para limitar el alcance de la búsqueda (agregada como `project = 'KEY' AND ...`).
`max_results`	`integer`	No	`50`	Número máximo de issues a incluir en los datos brutos del informe.
`summarize`	`boolean`	No	`false`	Si es `true`, el servidor solicitará un resumen al LLM del cliente a través de `ctx.sample()`.

📦 Dependencias del Servidor

El constructor de FastMCP incluye dependencies=["jira"]. Esto les indica a herramientas como fastmcp install que la librería jira es necesaria para que este servidor funcione correctamente al crear entornos aislados.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar issues o solicitudes de extracción.

📄 Licencia

Licencia MIT