Jira Weekly Reporter MCP Server

Servidor MCP de Jira Weekly Reporter

Este proyecto proporciona un servidor FastMCP que se conecta a su instancia de Jira (nube o servidor/centro de datos) para generar informes semanales basados en la actividad de incidencias. Utiliza la biblioteca pycontribs-jira para la interacción con Jira y, opcionalmente, puede usar el Modelo de Lenguaje Grande (LLM) del cliente conectado para resumir el informe generado.

✨ Características

• Conexión Jira: se conecta de forma segura a Jira mediante tokens 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:
  • El valor predeterminado es informar problemas actualizados en los últimos 7 días.
  • Permite especificar una consulta JQL personalizada.
  • Puede filtrar informes por una clave de proyecto de Jira específica.
  • Limita el número de resultados devueltos (configurable).
• (Opcional) Resumen de LLM: se puede utilizar el LLM del cliente (a través de ctx.sample() ) para proporcionar un resumen conciso del informe.
• Manejo asincrónico: maneja adecuadamente las llamadas sincrónicas de la biblioteca Jira dentro del servidor FastMCP asincrónico 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 (nube, servidor o centro de datos).
• Un token de API de Jira (token de acceso personal para servidor/DC).
• FastMCP CLI instalado y disponible en la RUTA de su sistema.

⚙️ Configuración

1. Clonar el repositorio (si corresponde):
   git clone https://github.com/Jongryong/jira_reporter.git cd jira_reporter
2. Instalar dependencias: Recomendamos utilizar uv :
   uv pip install fastmcp "jira[cli]" python-dotenv httpx anyio
   Alternativamente, utilice pip :
   pip install fastmcp "jira[cli]" python-dotenv httpx anyio
3. Crear archivo .env : Cree un archivo llamado .env en el mismo directorio que jira_reporter_server.py . Agregue los datos de su conexión de 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 envíes tu archivo .env al control de versiones! Agrega .env a tu archivo .gitignore .
     • Jira Cloud: genere un token de API desde la configuración de su cuenta de Atlassian: Administrar tokens de API .
     • Jira Server/Data Center: Genere un token de acceso personal (PAT) a partir de la configuración de su perfil de usuario de Jira: Uso de tokens de acceso personal .

▶️ Ejecución del servidor (independiente)

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

1. Directamente con Python:
   python jira_reporter_server.py
2. 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 que este servidor esté disponible como herramienta dentro de la aplicación Claude Desktop:

1. Asegúrese de cumplir con los requisitos previos: asegúrese de que fastmcp esté instalado y accesible en la RUTA de su sistema, ya que la configuración a continuación utiliza el comando fastmcp .
2. Localizar el archivo de configuración de Claude: Busca el archivo claude_desktop_config.json . Su ubicación depende del sistema operativo:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json (normalmente C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json )
   • Linux: ~/.config/Claude/claude_desktop_config.json (o $XDG_CONFIG_HOME/Claude/ )
3. Editar el archivo de configuración: abra claude_desktop_config.json en un editor de texto.
4. Añadir la configuración del servidor: Busca el objeto "mcpServers" en el 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 dice a Claude que use la herramienta de línea de comandos fastmcp .
   • "args": [...] : Le dice a Claude que ejecute fastmcp run /path/to/your/jira_reporter_server.py .
5. Guardar y reiniciar: guarde el archivo claude_desktop_config.json y reinicie la aplicación Claude Desktop.
6. Invocar la herramienta: Ahora debería 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 incidencias de Jira basado en una consulta JQL (el valor predeterminado es "actualizado recientemente"). Opcionalmente, resume el informe utilizando el LLM del cliente.

Parámetros:

Dependencias del servidor

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

🤝 Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar incidencias o solicitudes de incorporación de cambios.

📄 Licencia

Licencia MIT