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