Jira Service Management MCP Server

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

# 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ę:

   copy .env.example .env
   # Edytuj .env i dodaj swoje dane
   

3. Skonfiguruj MCP Client:

   Zobacz przykłady konfiguracji w katalogu examples/:

   • examples/mcp-settings-example.json - dla Roo Code
   • 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

# 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

{
  "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/

💡 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
• Mapowanie API
• Szablony konfiguracji
• Plan implementacji

🔒 Security

Bezpieczeństwo jest priorytetem! Zobacz naszą Politykę Bezpieczeństwa, 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, 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

# 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
2. Pełny przewodnik: docs/PRZEWODNIK-ROZWIAZYWANIE-401.md
3. Kompletna dokumentacja: docs/README.md

Testy Diagnostyczne

Katalog testy/ zawiera skrypty do diagnozowania problemów:

# 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/
2. Uruchom testy diagnostyczne z testy/
3. Zweryfikuj uprawnienia API token
4. Sprawdź logi serwera MCP

📄 Licencja

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

---

Made with ❤️ for the Atlassian Community