# Jira Service Management MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D%2018.0.0-brightgreen.svg)](package.json)

Serwer MCP (Model Context Protocol) umożliwiający konfigurację Jira Service Management Cloud za pomocą języka naturalnego.

## ✨ Funkcje

- ✅ Zarządzanie typami wniosków (Request Types)
- ✅ Konfiguracja formularzy z walidacją
- ✅ Tworzenie i zarządzanie polami niestandardowymi
- ✅ Zarządzanie workflow (podstawowe operacje)
- ✅ Konfiguracja SLA (odczyt i monitoring)
- ✅ Zarządzanie grupami i uprawnieniami
- ✅ Narzędzia pomocnicze (listowanie, wyszukiwanie, walidacja)

## 🚀 Quick Start

### 1. Instalacja

```bash
# Sklonuj repozytorium
git clone https://github.com/lukaszdrab-DWB/jira-service-management-mcp.git
cd jira-service-management-mcp

# Zainstaluj zależności
npm install

# Zbuduj projekt
npm run build
```

### 2. Konfiguracja

1. **Uzyskaj Jira API Token**:
   - Przejdź do: https://id.atlassian.com/manage-profile/security/api-tokens
   - Kliknij "Create API token"
   - Nazwij token (np. "MCP Server") i skopiuj go

2. **Skopiuj przykładową konfigurację**:
   ```bash
   copy .env.example .env
   # Edytuj .env i dodaj swoje dane
   ```

3. **Skonfiguruj MCP Client**:
   
   Zobacz przykłady konfiguracji w katalogu [`examples/`](examples/):
   - [`examples/mcp-settings-example.json`](examples/mcp-settings-example.json) - dla Roo Code
   - [`examples/claude-desktop-config.json`](examples/claude-desktop-config.json) - dla Claude Desktop

## 📋 Wymagania

- Node.js >= 18.x
- npm >= 9.x
- Jira Cloud API Token
- Uprawnienia: Jira Administrator lub Service Desk Administrator

## 🔧 Instalacja Szczegółowa

```bash
# Sklonuj repozytorium
git clone <repository-url>
cd jira-service-management-mcp

# Zainstaluj zależności
npm install

# Zbuduj projekt
npm run build
```

## ⚙️ Konfiguracja MCP

### Konfiguracja w MCP Client

Dodaj serwer do pliku `mcp_settings.json`:

**Windows:** `%APPDATA%\roo-code\settings\mcp_settings.json`
**macOS/Linux:** `~/.roo-code/settings/mcp_settings.json`

```json
{
  "mcpServers": {
    "jira-service-management": {
      "command": "node",
      "args": ["C:/path/to/jira-service-management-mcp/build/index.js"],
      "env": {
        "JIRA_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      },
      "disabled": false,
      "alwaysAllow": [],
      "disabledTools": []
    }
  }
}
```

> 💡 **Wskazówka**: Zobacz pełne przykłady w katalogu [`examples/`](examples/)

## 💡 Użycie

Po skonfigurowaniu, serwer udostępnia narzędzia MCP, które możesz używać poprzez Roo Code lub Claude Desktop:

### Przykład 1: Tworzenie pola niestandardowego

```
Stwórz pole niestandardowe "Budynek" typu select z opcjami: Budynek A, Budynek B, Budynek C
```

### Przykład 2: Tworzenie typu wniosku

```
Utwórz request type "Zgłoszenie problemu IT" w Service Desk o ID 10 z opisem "Zgłaszanie problemów technicznych"
```

### Przykład 3: Konfiguracja formularza

```
Skonfiguruj formularz dla request type 15 z polami:
- summary (wymagane, min 10 znaków)
- description (wymagane, min 30 znaków)
- priority (wymagane)
```

## 🛠️ Dostępne Narzędzia

### Request Types (4 narzędzia)
- `create_request_type` - Tworzenie nowego typu wniosku
- `update_request_type` - Modyfikacja typu wniosku
- `list_request_types` - Lista wszystkich typów wniosków
- `get_request_type_fields` - Pobierz pola dla typu wniosku

### Custom Fields (4 narzędzia)
- `create_custom_field` - Tworzenie pola niestandardowego
- `list_custom_fields` - Lista wszystkich pól
- `add_custom_field_context` - Dodanie kontekstu pola
- `update_custom_field_options` - Aktualizacja opcji dla select fields

### Utilities (4 narzędzia)
- `list_service_desks` - Lista projektów Service Desk
- `get_project_config` - Pobierz konfigurację projektu
- `search_issues` - Wyszukiwanie zgłoszeń (JQL)
- `validate_configuration` - Walidacja konfiguracji

(i więcej - patrz pełna dokumentacja)

## 📚 Dokumentacja

- [Architektura](../plans/jira-service-management-mcp-architecture.md)
- [Mapowanie API](../plans/jira-api-endpoints-mapping.md)
- [Szablony konfiguracji](../plans/example-templates.md)
- [Plan implementacji](../plans/implementation-roadmap.md)

## 🔒 Security

Bezpieczeństwo jest priorytetem! Zobacz naszą [Politykę Bezpieczeństwa](SECURITY.md), która zawiera:

- Jak bezpiecznie zgłaszać luki bezpieczeństwa
- Najlepsze praktyki dotyczące API tokenów
- Wspierane wersje i aktualizacje bezpieczeństwa

⚠️ **Nigdy nie commituj API tokenów lub danych wrażliwych!**

## 🤝 Contributing

Chcesz pomóc w rozwoju projektu? Zobacz nasz [Przewodnik Współtworzenia](CONTRIBUTING.md), który zawiera:

- Jak zgłaszać błędy
- Jak proponować nowe funkcje
- Setup środowiska deweloperskiego
- Proces Pull Request
- Wytyczne dotyczące kodu

## ⚠️ Ograniczenia

- **Workflow:** Tworzenie workflow przez API jest ograniczone, wspierane jest przypisywanie istniejących
- **SLA:** Konfiguracja SLA wymaga UI, API pozwala na odczyt
- **Rate Limits:** 300 żądań/minutę dla Jira Cloud

## 🔧 Rozwój

```bash
# Watch mode - automatyczne przebudowanie po zmianach
npm run watch

# Budowanie
npm run build

# Uruchomienie dev
npm run dev
```

## 🔍 Diagnostyka i Rozwiązywanie Problemów

### Problem HTTP 401 Unauthorized

Jeśli napotkasz błąd 401 podczas łączenia z Jira API:

1. **Przeczytaj finalna diagnozę**: [`docs/RAPORT-DIAGNOZA-FINALNA.md`](docs/RAPORT-DIAGNOZA-FINALNA.md)
2. **Pełny przewodnik**: [`docs/PRZEWODNIK-ROZWIAZYWANIE-401.md`](docs/PRZEWODNIK-ROZWIAZYWANIE-401.md)
3. **Kompletna dokumentacja**: [`docs/README.md`](docs/README.md)

### Testy Diagnostyczne

Katalog [`testy/`](testy/) zawiera skrypty do diagnozowania problemów:

```bash
# Test połączenia z autoryzacją
node testy/test-connection.js

# Diagnoza autoryzacji (szczegółowa)
node testy/debug-auth.js

# Test endpointu bez autoryzacji
node testy/test-no-auth-endpoint.js

# Test różnych wariantów URL
node testy/test-url-variants.js

# Test Cloud ID URL
node testy/test-cloudid-url.js
```

### Struktura Projektu

```
jira-service-management-mcp/
├── .github/        # Szablony GitHub (Issues, PRs)
├── docs/           # Dokumentacja diagnostyczna błędów
├── examples/       # Przykłady konfiguracji
├── src/            # Kod źródłowy MCP serwera
├── testy/          # Skrypty testowe i diagnostyczne
├── .env.example    # Przykładowa konfiguracja
├── LICENSE         # Licencja MIT
├── SECURITY.md     # Polityka bezpieczeństwa
├── CONTRIBUTING.md # Przewodnik współtworzenia
└── README.md       # Ten plik
```

## 🆘 Wsparcie

W przypadku problemów:
1. Sprawdź dokumentację w [`docs/`](docs/)
2. Uruchom testy diagnostyczne z [`testy/`](testy/)
3. Zweryfikuj uprawnienia API token
4. Sprawdź logi serwera MCP

## 📄 Licencja

Projekt jest dostępny na licencji MIT - zobacz plik [LICENSE](LICENSE) dla szczegółów.

---

**Made with ❤️ for the Atlassian Community**