# JIRA MCP Server per Claude Code

Server MCP che espone le operazioni JIRA a Claude Code, pensato per reti aziendali (es. Enel intranet).

## Prerequisiti

- Node.js 18+
- Accesso a `jira.springlab.enel.com` dalla macchina
- Personal Access Token JIRA (PAT)

## Installazione

```bash
# 1. Installa le dipendenze
npm install

# 2. Crea il file .env dalla copia di esempio
copy .env.example .env

# 3. Modifica .env con il tuo token e URL
notepad .env

# 4. Compila TypeScript
npm run build
```

## Configurazione `.env`

```env
JIRA_BASE_URL=https://jira.springlab.enel.com
JIRA_TOKEN=il_tuo_pat_qui
JIRA_API_VERSION=2
```

> **Come ottenere il PAT:** JIRA → click sul tuo avatar → *Profilo* → *Sicurezza* → *Token di accesso personale* → Crea token

## Configurazione Claude Code

### Opzione A — Configurazione locale al progetto (`.mcp.json`)

Il file `.mcp.json` è già presente nella root. Quando lanci `claude` da questa cartella, viene rilevato automaticamente.

Verifica che il percorso `cwd` nel file corrisponda alla tua installazione:

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "C:\\VSCWorkspace\\Progetti\\jiraMCP"
    }
  }
}
```

### Opzione B — Configurazione globale (`~/.claude/mcp.json`)

Aggiunge il server a tutte le sessioni Claude Code:

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["C:\\VSCWorkspace\\Progetti\\jiraMCP\\dist\\index.js"]
    }
  }
}
```

### Opzione C — Estensione VS Code Claude Code

Nell'estensione apri i settings MCP e aggiungi la stessa configurazione dell'Opzione B.

## Avvio manuale (debug)

```bash
# Modalità sviluppo (senza build)
npm run dev

# Modalità produzione
npm start
```

## Interfaccia Web Locale (senza VS Code)

Puoi usare una UI minimale da browser per invocare i tool MCP.

```bash
# 1) Build del server MCP
npm run build

# 2) Avvio UI locale
npm run ui
```

Apri poi: `http://127.0.0.1:8787`

Endpoint disponibili:

- `GET /api/tools` -> lista tool disponibili
- `POST /api/call` -> invoca un tool (`{ "name": "...", "arguments": { ... } }`)
- `POST /api/nl-call` -> prompt naturale + traduzione AI (`{ "prompt": "...", "execute": true }`)
- `POST /api/restart` -> riavvia il processo MCP usato dalla UI

Variabili opzionali:

- `MCP_UI_HOST` (default: `127.0.0.1`)
- `MCP_UI_PORT` (default: `8787`)

Per la modalità linguaggio naturale (AI):

- `NL_AI_API_KEY` (obbligatoria)
- `NL_AI_MODEL` (default: `gpt-4o-mini`)
- `NL_AI_BASE_URL` (default: `https://api.openai.com/v1`)

Esempio `.env`:

```env
NL_AI_API_KEY=sk-...
NL_AI_MODEL=gpt-4o-mini
NL_AI_BASE_URL=https://api.openai.com/v1
```

## Strumenti disponibili

| Tool | Descrizione |
|------|-------------|
| `jira_search` | Cerca issue con query JQL |
| `jira_get_issue` | Dettagli completi di una issue |
| `jira_create_issue` | Crea una nuova issue |
| `jira_update_issue` | Aggiorna campi di una issue |
| `jira_add_comment` | Aggiungi commento |
| `jira_get_transitions` | Elenca transizioni di stato disponibili |
| `jira_transition_issue` | Cambia stato a una issue |
| `jira_get_projects` | Lista progetti accessibili |
| `jira_assign_issue` | Assegna issue a un utente |
| `jira_get_issue_comments` | Leggi commenti di una issue |

## Esempi di utilizzo in Claude Code

```
# Cerca bug aperti
"cerca le issue con JQL: project = MYPROJ AND issuetype = Bug AND status != Done"

# Crea una task
"crea una task nel progetto ABC con titolo 'Aggiornare documentazione API'"

# Aggiorna stato
"porta la issue ABC-123 in Done"

# Aggiungi commento
"aggiungi un commento a ABC-456: 'Fix verificato in staging'"
```

## Struttura progetto

```
jiraMCP/
├── src/
│   └── index.ts          # MCP server principale
├── dist/                 # Output compilato (generato da npm run build)
├── .env                  # Le tue credenziali (NON committare!)
├── .env.example          # Template variabili d'ambiente
├── .mcp.json             # Config MCP per Claude Code (progetto locale)
├── package.json
└── tsconfig.json
```

## Sicurezza

- Il file `.env` non deve mai essere committato (aggiunto al `.gitignore`)
- Il token transita solo su connessioni interne verso JIRA
- Nessun dato viene inviato a server esterni