JIRA MCP Server

Это сервер Model Context Protocol (MCP), который предоставляет инструменты для взаимодействия с JIRA. Он позволяет получать тикеты из активных спринтов и подробную информацию о тикетах через интерфейс MCP.

Возможности

Сервер предоставляет следующие инструменты:

1. list-sprint-tickets: получает все тикеты в активном спринте для указанного проекта

   • Обязательный параметр: projectKey (строка)

2. get-ticket-details: получает подробную информацию о конкретном тикете

   • Обязательный параметр: issueKey (строка)

3. add-comment: добавляет комментарий к конкретному тикету

   • Обязательный параметр: issueKey (строка)

   • Либо comment (строка), либо filePath (строка) — см. Редактирование содержимого из файла

   • Необязательный параметр: commentFormat — plain (по умолчанию), wiki, markdown или adf

4. link-tickets: связывает два тикета отношением 'relates to'

   • Обязательный параметр: sourceIssueKey (строка)

   • Обязательный параметр: targetIssueKey (строка)

5. update-description: обновляет описание конкретного тикета

   • Обязательный параметр: issueKey (строка)

   • Либо description (строка), либо filePath (строка) — см. Редактирование содержимого из файла

   • Необязательный параметр: descriptionFormat — plain (по умолчанию), wiki, markdown или adf

6. list-child-issues: получает все дочерние задачи родительского тикета

   • Обязательный параметр: parentKey (строка)

7. create-sub-ticket: создает подтикет (дочернюю задачу) для родительского тикета

   • Обязательный параметр: parentKey (строка)

   • Обязательный параметр: summary (строка)

   • Необязательный параметр: description (строка) или filePath (строка) — см. Редактирование содержимого из файла

   • Необязательный параметр: issueType (строка) — название типа подзадачи (например, 'Sub-task')

Related MCP server: mcp-jira

Настройка

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

   npm install

2. Соберите TypeScript-код:

Этот шаг нужен только для Cline на Windows, где сейчас возникает проблема с выполнением npx

npm run build

3. Настройте параметры MCP в файле настроек вашего приложения Claude (обычно он находится по пути ~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json на Windows):

Настройки для Claude:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["path/to/this/repo/jira.ts"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Настройки для Cline:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["path/to/this/repo/dist/jira.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Конфигурация

Вам нужно настроить следующие переменные окружения в параметрах MCP:

1. JIRA_HOST: URL вашего домена Atlassian (например, https://your-company.atlassian.net)

2. JIRA_EMAIL: email вашей учетной записи JIRA

3. JIRA_API_TOKEN: ваш API-токен JIRA

   • Вы можете сгенерировать API-токен в настройках учетной записи Atlassian

Использование

После настройки вы можете использовать инструменты через интерфейс MCP в Claude:

Список тикетов спринта

Чтобы получить все тикеты активного спринта для проекта:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>list-sprint-tickets</tool_name>
<arguments>
{
  "projectKey": "YOUR_PROJECT_KEY"
}
</arguments>
</use_mcp_tool>

Получение сведений о тикете

Чтобы получить подробную информацию о конкретном тикете:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>get-ticket-details</tool_name>
<arguments>
{
  "issueKey": "PROJECT-123"
}
</arguments>
</use_mcp_tool>

Редактирование содержимого из файла

update-description, update-comment, add-comment, create-ticket и create-sub-ticket принимают filePath вместо встроенного текста. Это предназначено для длинного содержимого: храните исходный текст в файле, редактируйте этот файл и отправляйте снова — нет необходимости каждый раз повторно передавать весь текст через вызов инструмента. В двух инструментах создания описание остается необязательным, поэтому можно не указывать ни то, ни другое.

Формат определяется по расширению файла, поэтому descriptionFormat / commentFormat можно не указывать:

Явная передача формата переопределяет расширение; это также способ использовать файл с любым другим расширением. Пути могут быть абсолютными или относительными к рабочей директории сервера.

{
  "issueKey": "PROJECT-123",
  "filePath": "/abs/path/to/description.md"
}

Пустой файл отклоняется, а не затирает существующее описание или комментарий; передача одновременно и встроенного текста, и filePath является ошибкой.

Изменение существующего содержимого

Чтобы изменить часть уже существующего описания или комментария, сначала экспортируйте его с помощью export-content, отредактируйте файл и загрузите его снова — не нужно переписывать все целиком:

{ "issueKey": "PROJECT-123", "commentId": "54660", "filePath": "/tmp/pir-timeline.md" }

Экспорт сообщает, безопасно ли загружать это содержимое обратно как markdown. Jira хранит содержимое в формате ADF, и такие конструкции, как панели, упоминания, статусные плашки, медиафайлы, таблицы, списки задач и раскрывающиеся блоки, не имеют markdown-эквивалента — повторная загрузка markdown молча удалит их. Если такие элементы присутствуют, инструмент предупреждает и перечисляет их; вместо этого экспортируйте с "format": "adf" и изменяйте JSON, который всегда проходит полный цикл без изменений (.json-файлы распознаются как ADF при загрузке).

Если опустить filePath, содержимое будет возвращено непосредственно в ответе, а не записано в файл. Идентификаторы комментариев отображаются в get-ticket-details.

Версии содержимого (оптимистическая конкурентность)

update-description и update-comment требуют expectedVersion всякий раз, когда заменяемое содержимое не пусто: это версия, на которой основывалось изменение. Если с тех пор содержимое в Jira изменилось, обновление отклоняется, а не молча отбрасывает это изменение — та же блокировка, которую Confluence получает благодаря номерам версий страниц.

В Jira нет собственного номера версии, а временная метка updated задачи не является заменой: она обновляется при любом изменении задачи, поэтому переходы, метки и новые комментарии приводили бы к отклонению патчей описания, которые на самом деле не конфликтовали. Поэтому версия — это хэш самого содержимого (v1-…), и она меняется ровно тогда, когда меняется то, что патчится.

Версии можно получить из export-content и из get-ticket-details, который выводит Description version: и version: для каждого комментария — так что для небольшого изменения не нужен цикл экспорта.

Для первой записи описания версия не нужна. Сам пропуск expectedVersion является утверждением «здесь еще ничего нет», которое проверяет сервер: запись проходит, когда описание все еще пустое, и отклоняется — с указанием версии, которая сейчас в Jira, — если кто-то тем временем его записал. Таким образом, блокировка распространяется и на первую запись, и вызывающему коду не нужно получать версию пустого содержимого.

Передайте "force": true, чтобы пропустить проверку и перезаписать содержимое в любом случае.

Разработка

Сервер написан на TypeScript и использует:

• @modelcontextprotocol/sdk для реализации MCP-сервера

• jira.js для интеграции с JIRA API

Рекомендуемые скрипты:

• Сборка один раз: npm run build

• Сборка и наблюдение за файлами: npm run build:watch

• Только проверка типов: npm run typecheck

• Запуск для разработки с watch: npm run start:dev

• Запуск скомпилированного сервера: npm start

• Проверка форматирования: npm run fmt:check

• Применение форматирования: npm run fmt

Типичный рабочий процесс:

1. Внесите изменения в jira.ts

2. Запустите npm run start:dev во время разработки или npm run build, а затем npm start для запуска скомпилированной версии

3. При необходимости перезапустите ваш MCP-клиент, чтобы изменения вступили в силу

Обработка ошибок

Сервер включает обработку ошибок для:

• Неверные учетные данные JIRA

• Отсутствие активных спринтов

• Неверные ключи проектов или ключи задач

• Сетевые ошибки

Сообщения об ошибках будут возвращены в ответе инструмента.