Jira Weekly Reporter

Conecta-se a uma instância do Jira para gerar relatórios semanais com base na atividade de issues.

Documentação

Servidor MCP Jira Weekly Reporter

Este projeto fornece um servidor FastMCP que se conecta à sua instância do Jira (Cloud ou Server/Data Center) para gerar relatórios semanais com base na atividade de issues. Ele utiliza a biblioteca pycontribs-jira para interação com o Jira e pode opcionalmente usar o Modelo de Linguagem Grande (LLM) do cliente conectado para resumir o relatório gerado.

✨ Recursos

Conexão com o Jira: Conecta-se com segurança ao Jira usando tokens de API armazenados em um arquivo .env.
Ferramenta MCP: Expõe uma ferramenta generate_jira_report acessível através do Model Context Protocol.
Relatórios Flexíveis:
- Padrão: relata issues atualizadas nos últimos 7 dias.
- Permite especificar uma consulta JQL personalizada.
- Pode filtrar relatórios por uma chave de projeto específica do Jira.
- Limita o número de resultados retornados (configurável).
(Opcional) Resumo com LLM: Pode usar o LLM do cliente (via ctx.sample()) para fornecer um resumo conciso do relatório.
Tratamento Assíncrono: Lida adequadamente com chamadas síncronas da biblioteca do Jira dentro do servidor assíncrono FastMCP usando asyncio.to_thread.

📋 Pré-requisitos

Python 3.10 ou posterior.
uv (recomendado) ou pip para gerenciamento de pacotes.
Acesso a uma instância do Jira (Cloud, Server ou Data Center).
Um Token de API do Jira (Token de Acesso Pessoal para Server/DC).
CLI FastMCP instalado e disponível no PATH do seu sistema.

⚙️ Configuração

Clone o Repositório (se aplicável):

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

Instale as Dependências: Recomendamos usar uv:

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

Alternativamente, use pip:

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

Crie o Arquivo .env: Crie um arquivo chamado .env no mesmo diretório de jira_reporter_server.py. Adicione seus detalhes de conexão do 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
```
- Segurança:
  - Nunca envie seu arquivo .env para o controle de versão! Adicione .env ao seu arquivo .gitignore.
  - Jira Cloud: Gere um token de API nas configurações da sua conta Atlassian: Gerenciar tokens de API.
  - Jira Server/Data Center: Gere um Token de Acesso Pessoal (PAT) nas configurações do seu perfil de usuário do Jira: Usando Tokens de Acesso Pessoal.

▶️ Executando o Servidor (Independente)

Você pode executar o servidor de forma independente para testes ou outros fins:

Diretamente com Python:
```
python jira_reporter_server.py
```

Usando a CLI FastMCP:

fastmcp run jira_reporter_server.py

Para executar com SSE (por exemplo, para acesso remoto):

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

🖥️ Usando com o Claude Desktop

Para disponibilizar este servidor como uma ferramenta no aplicativo Claude Desktop:

Garanta os Pré-requisitos: Certifique-se de que fastmcp esteja instalado e acessível no PATH do seu sistema, pois a configuração abaixo usa o comando fastmcp.
Localize o Arquivo de Configuração do Claude: Encontre o arquivo claude_desktop_config.json. Sua localização depende do seu sistema operacional:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json (geralmente C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)
- Linux: ~/.config/Claude/claude_desktop_config.json (ou $XDG_CONFIG_HOME/Claude/)
Edite o Arquivo de Configuração: Abra claude_desktop_config.json em um editor de texto.
Adicione a Configuração do Servidor: Encontre o objeto "mcpServers" dentro do JSON (se não existir, crie-o como um objeto vazio {}). Adicione a seguinte entrada dentro de mcpServers, certificando-se de substituir "path/to/your/jira_reporter_server.py" pelo caminho absoluto para o seu 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 é o nome interno que o Claude usa. Você pode alterá-lo se desejar.
- "command": "fastmcp": Diz ao Claude para usar a ferramenta de linha de comando fastmcp.
- "args": [...]: Diz ao Claude para executar fastmcp run /path/to/your/jira_reporter_server.py.
Salve e Reinicie: Salve o arquivo claude_desktop_config.json e reinicie o aplicativo Claude Desktop.
Invoque a Ferramenta: Agora você deve conseguir usar a ferramenta no Claude mencionando o nome do servidor definido no script Python (Jira Weekly Reporter). Por exemplo: @Jira Weekly Reporter generate jira report for project MYPROJ and summarize it

🛠️ Detalhes da Ferramenta MCP

Nome da Ferramenta: generate_jira_report
Descrição: Gera um relatório de issues do Jira com base em uma consulta JQL (padrão: atualizadas recentemente). Opcionalmente, resume o relatório usando o LLM do cliente.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`jql_query`	`string`	Não	`updated >= -7d ORDER BY updated DESC`	Consulta JQL opcional. Se omitida, o padrão é usado.
`project_key`	`string`	Não	`None`	Chave de projeto opcional do Jira (ex.: "PROJ") para limitar o escopo da busca (adicionada como `project = 'KEY' AND ...`).
`max_results`	`integer`	Não	`50`	Número máximo de issues a incluir nos dados brutos do relatório.
`summarize`	`boolean`	Não	`false`	Se `true`, o servidor solicitará um resumo do LLM do cliente via `ctx.sample()`.

📦 Dependências do Servidor

O construtor FastMCP inclui dependencies=["jira"]. Isso informa a ferramentas como fastmcp install que a biblioteca jira é necessária para que este servidor funcione corretamente ao criar ambientes isolados.

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar issues ou pull requests.

📄 Licença

Licença MIT