MCP-сервер приоритезации задач GitHub

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

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

# 1. Install from npm (recommended)
npm install -g mcp-git-issue-priority

# 2. Authenticate (if not already using GitHub CLI)
gh auth login

# 3. Add to Claude Code (~/.claude.json)

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

# 4. Restart Claude Code and verify
# The MCP tools should appear when you run /mcp

Возможности

• Выбор задач на основе приоритета: Алгоритм детерминированного скоринга обеспечивает последовательную приоритизацию задач между сессиями.

• Блокировки, безопасные при конкурентном доступе: Файловая атомарная блокировка предотвращает выбор одной и той же задачи несколькими ИИ-сессиями.

• Управляемый рабочий процесс: 8-этапный рабочий процесс (выбор → исследование → ветка → реализация → тестирование → коммит → pr → проверка) с проверкой переходов.

• Автоматическая маркировка: Создает и управляет метками приоритета (P0-P3), типа (bug, feature, chore, docs) и статуса.

• Обнаружение устаревших блокировок: Автоматически обнаруживает и очищает блокировки от завершившихся процессов.

• Журнал аудита: Логирование всех операций в формате JSON Lines с хранением в течение 30 дней.

Установка

Предварительные требования

• Node.js 20+ - Скачать

• GitHub CLI (рекомендуется) - Установить и выполнить gh auth login

  • Или: персональный токен доступа GitHub с областью repo

Установка из npm (рекомендуется)

npm install -g mcp-git-issue-priority

Установка конкретной версии

npm install -g mcp-git-issue-priority@1.0.0

Установка из исходного кода

git clone https://github.com/steiner385/mcp-git-issue-priority.git
cd mcp-git-issue-priority
npm install && npm link

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

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

Аутентификация GitHub

Сервер поддерживает два метода аутентификации:

Рекомендуется: GitHub CLI (автоматически)

Если у вас установлен и аутентифицирован GitHub CLI, сервер автоматически получит ваш токен:

# One-time setup
gh auth login

Это рекомендуемый подход — ручное управление токенами не требуется.

Альтернатива: Переменная окружения

Установите GITHUB_TOKEN с помощью персонального токена доступа, имеющего область repo:

export GITHUB_TOKEN="ghp_your_personal_access_token"

Или настройте его в своих параметрах MCP (см. ниже).

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

Добавьте в ~/.claude.json (глобально) или .claude/settings.json (проект):

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

Используете персональный токен доступа вместо GitHub CLI? Добавьте токен в конфигурацию:

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority",
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token"
      }
    }
  }
}

Проверка установки

После перезапуска Claude Code:

1. Выполните /mcp, чтобы увидеть доступные MCP-серверы.

2. Сервер github-issue-priority должен быть в списке с 13 инструментами.

3. Попробуйте list_backlog в любом репозитории, чтобы убедиться, что он работает.

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

create_issue

Создание новой задачи GitHub с обязательными метками приоритета и типа.

Arguments:
  - title (required): Issue title
  - body (optional): Issue description
  - priority (required): P0 (critical) | P1 (high) | P2 (medium) | P3 (low)
  - type (required): bug | feature | chore | docs
  - repository (required): "owner/repo" format

select_next_issue

Выбор и блокировка задачи с наивысшим приоритетом из бэклога. Использует детерминированный скоринг для обеспечения последовательного выбора.

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - maxPriority (optional): Only consider issues at or above this priority

list_backlog

Список всех открытых задач в порядке приоритета без получения блокировок (только чтение).

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - limit (optional): Maximum issues to return (default: 20)

advance_workflow

Переход рабочего процесса к следующему этапу для заблокированной задачи.

Arguments:
  - issueNumber (required): Issue number to advance
  - targetPhase (required): research | branch | implementation | testing | commit | pr | review
  - repository (required): "owner/repo" format
  - testsPassed (optional): Required when advancing to 'commit' phase
  - prTitle (optional): Required for 'pr' phase
  - prBody (optional): Required for 'pr' phase
  - skipJustification (optional): Required if skipping phases

get_workflow_status

Получение текущего статуса рабочего процесса для заблокированных задач.

Arguments:
  - issueNumber (optional): Specific issue number
  - repository (optional): "owner/repo" format

release_lock

Снятие блокировки с задачи (при завершении, отказе или слиянии).

Arguments:
  - issueNumber (required): Issue number
  - reason (required): completed | abandoned | merged
  - repository (required): "owner/repo" format

force_claim

Принудительный захват задачи, заблокированной другой сессией (требуется подтверждение).

Arguments:
  - issueNumber (required): Issue number to claim
  - confirmation (required): Must be exactly "I understand this may cause conflicts"
  - repository (required): "owner/repo" format

sync_backlog_labels

Обнаружение и опциональное исправление задач, у которых отсутствуют обязательные метки приоритета/типа/статуса.

Arguments:
  - repository (required): "owner/repo" format
  - mode (optional): "report" (default) to list issues, "update" to apply labels
  - defaultPriority (optional): P0 | P1 | P2 | P3 (defaults to P2)
  - defaultType (optional): bug | feature | chore | docs (defaults to feature)

В режиме отчета возвращает список всех задач без меток с подробной информацией о том, чего не хватает.

В режиме обновления применяет метки по умолчанию к задачам:

• Отсутствует приоритет → priority:P2 (или указанный по умолчанию)

• Отсутствует тип → type:feature (или указанный по умолчанию)

• Отсутствует статус → status:backlog

get_pr_status

Проверка статуса CI, состояния одобрения и состояния слияния pull request.

Arguments:
  - repository (required): "owner/repo" format
  - prNumber (required): Pull request number to check

bulk_update_issues

Добавление/удаление меток и закрытие/открытие нескольких задач одновременно.

Arguments:
  - repository (required): "owner/repo" format
  - issues (required): Array of issue numbers (1-50)
  - addLabels (optional): Labels to add
  - removeLabels (optional): Labels to remove
  - state (optional): "open" | "closed"

implement_batch

Начало реализации пакета из N задач в порядке приоритета. Возвращает первую задачу для реализации.

Arguments:
  - repository (required): "owner/repo" format
  - count (required): Number of issues to implement (1-10)
  - includeTypes (optional): Only include these issue types
  - excludeTypes (optional): Exclude these issue types
  - maxPriority (optional): Only P0, P1, etc.

batch_continue

Продолжение пакетной реализации. Ожидает слияния PR, затем возвращает следующую задачу или завершение.

Arguments:
  - batchId (required): Batch ID from implement_batch
  - prNumber (optional): PR number for current issue

get_workflow_analytics

Получение аналитики рабочего процесса на основе времени: время цикла, разбивка по этапам, отчеты об устаревании.

Arguments:
  - repository (required): "owner/repo" format
  - period (optional): "7d" | "30d" | "90d" | "all" (default: 30d)

Алгоритм скоринга приоритетов

Задачи оцениваются по детерминированной формуле:

score = (basePoints + ageBonus) * blockingMultiplier * blockedPenalty

• Базовые баллы: P0=1000, P1=100, P2=10, P3=1

• Бонус за возраст: +1 балл за день с момента создания (макс. 365)

• Множитель блокировки: 1.5x для задач с меткой "blocking"

• Штраф за блокировку: 0.1x для задач, заблокированных открытыми родительскими задачами (через подзадачи GitHub)

• Тай-брейкер: Более ранняя дата создания выигрывает (FIFO)

Обнаружение зависимостей

Задачи с открытыми родительскими задачами (использующие функцию подзадач GitHub) автоматически понижаются в приоритете со штрафом 0.1x. Это гарантирует, что заблокированная работа опускается в конец бэклога до тех пор, пока ее зависимости не будут разрешены. Как только родительская задача закрывается, приоритет дочерней задачи возвращается к норме.

Этапы рабочего процесса

1. selection: Задача выбрана и заблокирована

2. research: Понимание проблемы

3. branch: Создана ветка функции

4. implementation: Изменения кода в процессе

5. testing: Запуск тестов и проверка

6. commit: Изменения зафиксированы

7. pr: Создан pull request

8. review: Ожидание проверки/слияния

Хранение данных

Все данные хранятся локально в ~/.mcp-git-issue-priority/:

~/.mcp-git-issue-priority/
├── locks/          # Active lock files (.lockdata)
├── workflow/       # Workflow state files (.json)
└── logs/           # Audit logs (JSON Lines format)

Разработка

Сборка

npm run build

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

npm test

Линтинг

npm run lint

Проверка типов

npm run typecheck

Релиз (для сопровождающих)

Однократная настройка

1. Создайте учетную запись npm на https://www.npmjs.com/

2. Перейдите на https://www.npmjs.com/settings/tokens

3. Создайте токен "Automation" с разрешением "Publish"

4. Добавьте в GitHub: Settings → Secrets → Actions → New secret с именем NPM_TOKEN

Создание релиза

# Patch release (bug fixes): 1.0.0 → 1.0.1
npm version patch -m "Release v%s"
git push && git push --tags

# Minor release (new features): 1.0.0 → 1.1.0
npm version minor -m "Release v%s"
git push && git push --tags

# Major release (breaking changes): 1.0.0 → 2.0.0
npm version major -m "Release v%s"
git push && git push --tags

Отправка тега запускает рабочий процесс релиза, который:

• Запускает линтинг, сборку и тесты

• Создает релиз GitHub с прикрепленным архивом

• Публикует в реестр npm

Отслеживание загрузок

• GitHub: Страница релизов показывает количество загрузок для каждого актива .tgz

• npm: https://www.npmjs.com/package/mcp-git-issue-priority показывает еженедельные загрузки

Лицензия

Лицензия MIT - подробности см. в LICENSE.

Участие в разработке

Вклад приветствуется! Пожалуйста, ознакомьтесь с CONTRIBUTING.md для получения рекомендаций.

Обратная связь и поддержка

Мы будем рады услышать вас! Ваши отзывы помогают улучшить этот инструмент для всех.

• Вопросы или идеи? Начните обсуждение

• Нашли ошибку? Откройте задачу

• Запрос на добавление функции? Откройте задачу с заголовком [Feature]

• Быстрая обратная связь? Выполните mcp-git-issue-priority --feedback, чтобы открыть страницу обратной связи

Проверьте существующие задачи перед созданием новых.