Jira MCP Server

Сервер протокола контекста модели (MCP), предоставляющий инструменты для взаимодействия с Jira. Позволяет Cursor и другим MCP-клиентам получать тикеты, управлять связанными тикетами и обновлять статус тикетов.

Быстрый старт

1. Установка зависимостей

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

2. Настройка учетных данных Jira

Рекомендуется: Токен личного доступа (PAT)

1. Войдите в Jira: https://jira.telekom.de

2. Перейдите в свой профиль > Personal Access Tokens

3. Нажмите "Create token"

4. Дайте ему имя (например, "Cursor MCP") и установите срок действия

5. Важно: Убедитесь, что у токена есть права "Read" или "Browse Projects"

6. Скопируйте токен сразу (вы не увидите его снова)

Создайте файл .env:

cp .env.example .env

Отредактируйте .env, указав свои учетные данные:

JIRA_URL=https://jira.telekom.de
JIRA_USERNAME=your.username@telekom.de
JIRA_API_TOKEN=your_personal_access_token_here
JIRA_AUTH_TYPE=bearer

Примечание: Токены API Kantega SSO могут иметь IP-ограничения или требовать разрешений, настроенных администратором. Токены личного доступа рекомендуются для большинства пользователей.

3. Настройка в Cursor

1. Откройте Cursor

2. Перейдите в Settings > Tools and MCP

3. Добавьте эту конфигурацию:

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jira-mcp",
        "run",
        "-m",
        "src"
      ]
    }
  }
}

Важно: Замените путь и учетные данные на ваши фактические значения!

4. Полностью перезапустите Cursor

4. Попробуйте в действии

В чате Cursor попробуйте:

• "Get details for Jira ticket PROJ-123"

• "Show me all linked tickets for PROJ-456"

• "Update PROJ-789 status to In Progress"

Функции

Доступные инструменты

Поддержка аутентификации

• Bearer Token: Токены личного доступа (PAT) - Рекомендуется

• Basic Auth: Имя пользователя + токен API (Atlassian Cloud)

• Cookie Auth: Аутентификация на основе сессии (резервный вариант)

Подробности об инструментах

get_ticket

Получает полную информацию о тикете.

Параметры:

• ticket_id (строка, обязательно): ID или ключ тикета (например, "PROJ-123")

Возвращает:

{
  "key": "PROJ-123",
  "summary": "Ticket summary",
  "description": "Detailed description",
  "status": "In Progress",
  "issue_type": "Story",
  "priority": "High",
  "assignee": "John Doe",
  "reporter": "Jane Smith",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-20T14:45:00.000+0000",
  "comments_count": 3,
  "comments": [...],
  "custom_fields": {...}
}

get_linked_tickets

Получает все связанные тикеты и подзадачи.

Параметры:

• ticket_id (строка, обязательно): ID или ключ тикета

Возвращает:

{
  "ticket": "PROJ-123",
  "linked_tickets": [
    {
      "link_type": "Blocks",
      "direction": "blocks",
      "key": "PROJ-124",
      "summary": "Related ticket",
      "status": "To Do"
    }
  ],
  "linked_tickets_count": 1,
  "subtasks": [...],
  "subtasks_count": 2
}

update_ticket_status

Обновляет статус тикета с проверкой рабочего процесса.

Параметры:

• ticket_id (строка, обязательно): ID или ключ тикета

• status (строка, обязательно): Целевой статус (например, "In Progress", "Done")

Возвращает:

Successfully updated ticket PROJ-123 status from 'To Do' to 'In Progress'

Примечание: Инструмент проверяет переходы. Если переход недействителен, он возвращает доступные переходы.

Тестирование

Запуск тестов

# Run all tests
.venv/bin/pytest tests/ -v

# Run with coverage
.venv/bin/pytest tests/ --cov=src -v

# Run specific test file
.venv/bin/pytest tests/test_integration/test_real_tickets.py -v

Ручное тестирование

Протестируйте сервер напрямую:

uv run --env-file .env -m src

Нажмите Ctrl+C для остановки.

Устранение неполадок

Ошибки аутентификации

Симптомы: "401 Unauthorized" или "403 Forbidden"

Решения:

• Наиболее часто: Токен личного доступа истек - создайте новый

• Проверьте, что ваш PAT имеет права "Read" или "Browse Projects"

• Проверьте, что ваше имя пользователя совпадает с адресом электронной почты вашей учетной записи Jira

• Убедитесь, что JIRA_URL включает https://

• Подтвердите, что JIRA_AUTH_TYPE=bearer для токенов личного доступа

Тикет не найден

Симптомы: "404 Not Found"

Решения:

• Проверьте правильность ключа тикета (например, "PROJ-123")

• Проверьте, есть ли у вас разрешение на просмотр тикета

• Убедитесь, что вы используете правильный экземпляр Jira

Сервер не появляется в Cursor

Решения:

• Проверьте абсолютный путь в настройках MCP

• Проверьте, установлен ли Python 3.12+: python3 --version

• Полностью перезапустите Cursor (закройте и откройте снова)

• Проверьте консоль разработчика Cursor на наличие ошибок

Невозможно изменить статус тикета

Симптомы: "Invalid status transition"

Решения:

• Сообщение об ошибке содержит список доступных переходов

• Имена статусов должны совпадать точно (регистронезависимо)

• Проверьте разрешения вашего рабочего процесса Jira

• Убедитесь, что переход действителен для вашего рабочего процесса

Архитектура

Этот проект следует принципам SOLID и чистой архитектуре:

src/
├── __init__.py
├── __main__.py           # Entry point
├── server.py             # MCP server setup
├── config/               # Configuration management
├── client/               # Jira API client
├── tools/                # 3 MCP tools
├── models/               # Domain models
├── mappers/              # Data transformation
└── utils/                # Error handling, JSON utils

Ключевые принципы:

• SOLID: Единственная ответственность, инверсия зависимостей

• DRY: Отсутствие дублирования, повторно используемые компоненты

• Безопасность типов: Полные подсказки типов повсюду

• Тестируемость: Четкое разделение ответственности

См. ARCHITECTURE.md для получения подробной технической документации.

Разработка

Структура проекта

jira-mcp/
├── src/                  # Source code (22 Python files)
├── tests/                # Test suite
├── pyproject.toml        # Project config (includes pytest config)
├── .env.example          # Config template
├── .gitignore
├── README.md             # This file
└── ARCHITECTURE.md       # Technical docs

Добавление зависимостей

uv add package-name

Запуск с другой конфигурацией

uv run --env-file .env.production -m src

Качество кода

• Ошибки линтинга: 0

• Покрытие типами: 100%

• Покрытие тестами: Интеграционные тесты для всех 3 инструментов

• Архитектура: Соответствует SOLID + DRY

Требования

• Python 3.12+

• Учетная запись Jira с доступом к API

• Токен API Jira (Kantega SSO Enterprise или Atlassian Cloud)

Лицензия

Этот проект предоставляется "как есть" для использования с Cursor и Jira.

Создано с использованием лучших практик, соответствующих принципам SOLID и DRY 🚀