npm package: @jeannohatto/jira-mcp-server
Description: MCP server for Jira (search, issues, worklogs) - private instance with Basic Auth
Latest version: 1.0.0

# Jira MCP Server

Servidor MCP para integração com Jira (instância privada – Server/Data Center). Oferece pesquisa por JQL, detalhes de issues e extração de worklogs (horas), com autenticação Basic (usuário e senha).

## Requisitos

- Node.js 18+
- Acesso a uma instância Jira (ex.: https://jira.senior.com.br) com usuário e senha

## Uso sem baixar os fontes (npx)

Depois que o pacote estiver publicado no npm (público ou registry privado), qualquer pessoa pode usar o MCP **sem clonar o repositório**. Basta configurar o Cursor com `npx`:

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://jira.senior.com.br",
        "JIRA_USERNAME": "seu_usuario",
        "JIRA_PASSWORD": "sua_senha"
      }
    }
  }
}
```

- `-y` evita que o npx pergunte se pode instalar o pacote.
- Na primeira vez o npx baixa o pacote; depois usa o cache.
- Não é necessário ter Node/npm no PATH de forma global em alguns clientes; o Cursor costuma fornecer o ambiente.

Se o pacote estiver em um **registry privado** (ex.: npm da empresa), use o nome scoped no `args`, por exemplo: `["-y", "@sua-empresa/jira-mcp-server"]`.

## Configuração (desenvolvimento local)

1. Copie o arquivo de exemplo e preencha com suas credenciais:

   ```bash
   cp .env.example .env
   ```

   Edite `.env` e defina:

   - `JIRA_BASE_URL` – URL base do Jira (sem barra no final), ex.: `https://jira.senior.com.br`
   - `JIRA_USERNAME` – seu usuário do Jira
   - `JIRA_PASSWORD` – sua senha

2. Instale as dependências e compile:

   ```bash
   npm install
   npm run build
   ```

## Execução

- **Modo stdio (padrão):** o Cursor inicia o processo e comunica via stdin/stdout.

  ```bash
  npm start
  ```

- **Modo HTTP (servidor na rede):** o MCP sobe um servidor HTTP e o Cursor conecta por URL. Defina a porta (e opcionalmente o host):

  ```bash
  set JIRA_MCP_HTTP_PORT=8080
  set JIRA_MCP_HTTP_HOST=0.0.0.0
  npm start
  ```

  - Sem `JIRA_MCP_HTTP_HOST` o servidor escuta só em `127.0.0.1` (localhost).
  - Com `JIRA_MCP_HTTP_HOST=0.0.0.0` o servidor aceita conexões de qualquer interface (rede local). Em outros PCs use `http://<IP-desta-máquina>:8080/mcp` no Cursor.
  - No mesmo PC: `http://localhost:8080/mcp`.
  - **Documentação:** com o servidor HTTP rodando, acesse `http://localhost:8080/mcp/doc` para a página de documentação (funcionalidades, configuração e exemplos).

- Modo desenvolvimento (com tsx):

  ```bash
  npm run dev
  ```

## Logs

Os logs são escritos em **stderr** (para não interferir no protocolo MCP em stdout). Cada linha é um JSON com `ts`, `level`, `msg` e dados opcionais.

- **Nível:** definido por `JIRA_MCP_LOG_LEVEL`: `debug` | `info` | `warn` | `error` (padrão: `info`).
- **Eventos:** início do servidor (baseUrl, user), cada chamada de tool (nome + argumentos), conclusão ou falha da tool, requisições à API Jira (em `debug`), erros e retentativas.

Para ver mais detalhes (incluindo cada request à API), use `JIRA_MCP_LOG_LEVEL=debug` no ambiente antes de `npm start` ou no `env` do MCP no Cursor.

## Configuração no Cursor

1. Abra as configurações do Cursor (MCP / Custom Instructions ou arquivo de configuração de MCPs, ex.: `mcp.json`).
2. Adicione o servidor de uma das formas abaixo.

   **Opção recomendada (sem baixar fontes)** – use após publicar no npm:

   - Comando: `npx`
   - Args: `["-y", "jira-mcp-server"]`
   - Env: `JIRA_BASE_URL`, `JIRA_USERNAME`, `JIRA_PASSWORD`

   **Opção com fontes locais** (desenvolvimento):

   - Comando: `node`
   - Args: caminho absoluto para `jira-mcp-server/dist/index.js`
   - Env: as mesmas variáveis acima

   **Opção modo HTTP (servidor em localhost):** use quando o MCP estiver rodando com `JIRA_MCP_HTTP_PORT=8080` (ou outra porta). No Cursor, para servidor remoto/HTTP usa-se `url` **no nível do servidor** (não dentro de `transport`):

   ```json
   {
     "mcpServers": {
       "jira": {
         "url": "http://localhost:8080/mcp"
       }
     }
   }
   ```

   Opcionalmente pode incluir `"headers": { ... }` se o servidor exigir autenticação por cabeçalho.

   As credenciais do Jira ficam no servidor (variáveis de ambiente onde o `npm start` foi executado), não no Cursor.

   Não commite o arquivo com senha; use variáveis de ambiente ou secretos quando possível.

## Tools disponíveis

| Tool | Descrição |
|------|-----------|
| `jira_check_connection` | Valida URL e credenciais; retorna dados do usuário atual ou erro. |
| `jira_list_projects` | Lista projetos acessíveis (key, id, name). |
| `jira_search_issues` | Busca issues por JQL (jql, startAt, maxResults, fields). |
| `jira_get_issue` | Detalhes completos de um issue pelo key. |
| `jira_get_worklogs` | Lista worklogs (horas) de um issue. |
| `jira_get_issue_or_epic_hours` | Total de horas da demanda. Se for Epic, soma as horas das issues vinculadas (onde as horas são lançadas). |
| `jira_get_issue_estimates` | Horas estimadas (Estimated), restantes (Remaining) e gastas (Time spent). Para Epic, soma das issues vinculadas quando a API retorna null no Epic. |

## Publicar no npm (para uso via npx)

Para que outros usem o MCP sem clonar o repositório:

1. **Registry público:** crie conta em [npmjs.com](https://www.npmjs.com/), faça `npm login` e publique:
   ```bash
   npm run build
   npm publish
   ```
   O script `prepublishOnly` roda o build antes de publicar. O campo `files` faz com que só a pasta `dist` (e arquivos padrão como package.json) entrem no pacote.

2. **Registry privado (ex.: npm da empresa):** configure o registry e o nome do pacote (ex.: `@sua-empresa/jira-mcp-server` no `package.json`). Depois:
   ```bash
   npm publish --access restricted
   ```
   Os usuários precisam estar logados no registry privado para `npx @sua-empresa/jira-mcp-server` funcionar.

3. **Testar localmente antes de publicar:** `npm pack` gera um `.tgz`; em outro diretório: `npm install /caminho/para/jira-mcp-server-1.0.0.tgz` e use `npx jira-mcp-server` de dentro desse projeto para validar.

## Instruções customizáveis

No repositório do projeto existe a pasta `mcps/user-mcp-jira/` com:

- **INSTRUCTIONS.md** – Instruções principais de uso do MCP (quando usar cada tool, JQL, fluxos). Edite conforme sua necessidade.
- **instructions/** – Arquivos por tema (pesquisas, demandas, horas, custom) para referência ou cópia para o INSTRUCTIONS.md.

Editar esses arquivos permite adaptar o comportamento do assistente ao usar o Jira.

## Segurança

- Não commite o arquivo `.env` nem credenciais em repositórios.
- Use variáveis de ambiente ou secretos do Cursor para `JIRA_PASSWORD`.
- O cliente não loga credenciais; em caso de erro 401, a mensagem orienta a verificar usuário e senha.