# Codex Jira Stories MCP

Servidor MCP local que permite ao Codex CLI consultar o Jira Cloud e publicar histórias já revisadas. Ele foi pensado para trabalhar com a skill local `jira-stories`: a skill redige a história; este servidor consulta o projeto e cria ou atualiza a issue.

## Segurança do fluxo

- As credenciais não ficam no repositório: são lidas de `JIRA_BASE_URL`, `JIRA_EMAIL` e `JIRA_API_TOKEN`.
- As ferramentas de escrita exigem `confirmPublish: true`.
- Não existe ferramenta de exclusão.
- Antes de publicar, use `jira_preview_issue` e confira o resultado.

## Preparação

1. Copie `.env.example` para um local seguro e exporte as variáveis no terminal. Não crie nem versione um arquivo `.env` com credenciais.
2. Confirme que a conta tem as permissões **Browse projects** e **Create issues** no projeto Jira desejado.
3. Registre o servidor no Codex CLI:

```bash
codex mcp add jira-stories \
  --env JIRA_BASE_URL="$JIRA_BASE_URL" \
  --env JIRA_EMAIL="$JIRA_EMAIL" \
  --env JIRA_API_TOKEN="$JIRA_API_TOKEN" \
  -- node /Users/emenezes/projetos/codex-jira-stories-mcp/src/server.mjs
```

Em seguida, abra uma nova sessão do Codex e execute `/mcp` para confirmar que `jira-stories` está ativo.

## Ferramentas disponíveis

| Ferramenta | Uso |
| --- | --- |
| `jira_list_projects` | Lista projetos visíveis à conta. |
| `jira_get_issue_types` | Lista tipos de issue de um projeto. |
| `jira_get_create_fields` | Mostra campos obrigatórios e editáveis para criar a issue. |
| `jira_search_issues` | Busca issues por JQL. |
| `jira_preview_issue` | Monta a prévia sem acessar nem alterar o Jira. |
| `jira_create_issue` | Cria uma issue, apenas com `confirmPublish: true`. |
| `jira_update_issue` | Atualiza os campos permitidos de uma issue, apenas com `confirmPublish: true`. |

## Exemplo de conversa

> Redija uma história funcional para permitir exportação de relatório PDF. Consulte os projetos Jira disponíveis, gere uma prévia para o projeto AGR, e só publique depois que eu aprovar.

Para publicar uma prévia aprovada, peça explicitamente ao Codex que use `jira_create_issue` com `confirmPublish: true`. A descrição é convertida de texto simples ou Markdown básico para o formato de documento aceito pelo Jira Cloud.

## Verificação local

```bash
npm test
```

## Limites atuais

Esta primeira versão atende Jira Cloud via API token. Para ambientes com SSO obrigatório ou requisito de autorização delegada, o próximo passo é trocar a autenticação por OAuth 2.0 no servidor MCP, preservando as mesmas ferramentas.