bitbucket-pr-review-mcp

MCP-сервер, который позволяет языковой модели читать pull request в Bitbucket Cloud и оставлять комментарии к нему — привязанные к строкам, к которым они относятся, плюс одно резюме вверху.

Сервер предоставляет материал и публикует слова. Он не формирует мнения: рецензирование выполняет вызывающая модель, и здесь нет ни промпта для рецензирования, ни учётных данных модели.

• Как это работает и почему: docs/architecture.md

• Решения, стоящие за этим: docs/adr/

• Язык, который он использует: CONTEXT.md

Что он не умеет

Он может создавать и обновлять комментарии. Он не может одобрить, отклонить или слить pull request, не может писать в ветки или файлы и никогда не удаляет комментарии.

Bitbucket не продаёт разрешение, которое отделяет комментирование от слияния. Учётные данные, которые вы даёте этому серверу, способны сливать ваши pull request; ни токены, ни области действия этому не препятствуют. Препятствует то, что ни один инструмент об этом не просит, что единственная точка контроля в HTTP-клиенте отказывает в этом, как бы ни был составлен запрос, и — та часть, которая не зависит от правильности этого кода — ограничения веток, которые вы настраиваете в репозитории самостоятельно. См. ADR-0002 и прочтите Перед началом работы.

Related MCP server: Bitbucket MCP Server

Перед началом работы

Настройте ограничения веток для любого репозитория, который вы добавляете в белый список. В Bitbucket: Настройки репозитория → Ограничения веток. Ограничьте, кто может сливать изменения в вашу основную ветку, и требуйте одобрений, которые ожидает ваша команда. Bitbucket применяет это независимо от того, что делает этот сервер, что делает это единственной гарантией здесь, которая переживёт ошибку в этом репозитории. Это занимает минуту, и это разница между «мы верим, что этот код осторожен» и «неважно, если это не так».

Установка

Требуется uv и Python 3.13. Те же три команды работают на Windows, macOS и Linux:

git clone <this repository>
cd bitbucket-pr-review-mcp
uv sync

Затем укажите, к каким репозиториям он может обращаться:

cp config/repositories.yaml.example config/repositories.yaml

...и отредактируйте его. Файл перечисляет записи workspace/repo, не содержит секретов и предназначен для коммита:

repositories:
  - streamstech/db-explorer
  - streamstech/lent-manager

Целое рабочее пространство можно записать как jantrik/*. Это самая широкая запись здесь — она охватывает репозитории, созданные после того, как вы её написали, — поэтому сервер говорит об этом при каждом запуске:

repositories:
  - jantrik/*

Сервер отказывается запускаться без списка. Отсутствующий список неотличим от разрешения касаться каждого репозитория, доступного вашим учётным данным. Шаблоны уже целого рабочего пространства (*/db-explorer, streamstech/db-*) отклоняются по той же причине: это догадки о именовании, и они захватывают всё, что будет названо так в следующий раз.

Подключение вашей учётной записи Bitbucket

Запустите настройку и откройте ссылку, которую она выводит:

uv run bb-pr-mcp --setup

Она обслуживает страницу на вашей собственной машине — только loopback, на случайном порту, одноразовая ссылка, исчезает через пять минут — запрашивая ваш email учётной записи Atlassian (не имя пользователя Bitbucket и не имя, которое вы дали токену) и API-токен. Она проверяет пару на Bitbucket и показывает ваше отображаемое имя перед сохранением чего-либо, затем помещает учётные данные в связку ключей вашей ОС и закрывается.

Создайте токен на https://id.atlassian.com/manage-profile/security/api-tokens с ровно этими четырьмя областями:

Ничего шире. Токен, который также может писать в репозиторий, администрировать его или запускать пайплайны, отклоняется в форме и снова отклоняется при запуске.

Введите дату истечения токена при настройке, и вы будете предупреждены за неделю до его истечения, а не столкнётесь с 401 в середине ревью.

Вам никогда не нужно запускать --setup явно: если учётные данные не сохранены, каждый инструмент отвечает URL-адресом настройки вместо ошибки.

Проверяйте это когда угодно:

uv run bb-pr-mcp --check

Это проверяет белый список, учётные данные и их области, выводит, от чьего имени вы публикуете, и завершается с кодом оболочки — 0 нормально, 1 нет пригодных учётных данных, 2 токен с неправильными областями.

Удаление

uv run bb-pr-mcp --forget

Это удаляет учётные данные из связки ключей этого устройства и ничего больше — токен по-прежнему существует в Atlassian, пока вы не отзовёте его там, и команда говорит об этом. Следующий вызов инструмента выдаст вам новую ссылку настройки.

Здесь намеренно нет инструмента для этого. Инструмент, который удаляет учётные данные, — это инструмент, который описание pull request может уговорить модель вызвать, и ничего не выигрывается: тот, кто хочет их удалить, уже находится в терминале.

Модель никогда не видит токен

Токен идёт из вашего браузера в связку ключей, а оттуда в заголовок Authorization. Он никогда не является аргументом инструмента, никогда не находится в ответе инструмента, никогда не находится в сообщении об ошибке и не находится в URL-адресе настройки — тот несёт другой одноразовый токен, который даёт только право заполнить одну форму на этой машине. tests/test_the_token_never_reaches_the_model.py ищет его во всех этих местах.

Если связка ключей недоступна

Учётные данные помещаются в связку ключей ОС и никуда больше — никогда в файл. На macOS и Windows это работает из коробки. На Linux вам нужна запущенная и разблокированная служба Secret Service (gnome-keyring или KWallet); если её нет, сервер останавливается, а не переключается на файл (ADR-0003).

Запуск

Сервер говорит по MCP через stdio. Укажите на него вашему клиенту:

{
  "mcpServers": {
    "bitbucket-pr-review": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/bitbucket-pr-review-mcp", "bb-pr-mcp"]
    }
  }
}

На Windows используйте ту же форму с путём Windows ("C:\\path\\to\\bitbucket-pr-review-mcp"). В остальном между платформами нет различий.

Для Claude Code:

claude mcp add bitbucket-pr-review -- uv run --directory /path/to/bitbucket-pr-review-mcp bb-pr-mcp

Запуск в Docker

Образ говорит по MCP через stdio, как и всё остальное, поэтому нет порта и ничего не нужно up. Соберите его, затем запустите с -i и общайтесь с ним.

docker build -t bitbucket-pr-review-mcp:local .

В контейнере нет связки ключей, и страница настройки не поможет: она привязывает порт loopback внутри контейнера, до которого ваш браузер не может добраться. Поэтому контейнерный запуск получает свои учётные данные, а не хранит их. Это реальное понижение — переменная окружения видна docker inspect и всему, что может читать процесс, — и это решение, а не запасной вариант: ничто не деградирует в него, обе переменные должны быть установлены, и запуск говорит об этом каждый раз. См. ADR-0007.

Поместите учётные данные в файл, который не находится в этом репозитории:

BB_MCP_EMAIL=you@yourcompany.com
BB_MCP_API_TOKEN=ATATT...
BB_MCP_TOKEN_EXPIRES_ON=2027-08-24

Затем проверьте его и подключите к клиенту:

docker run --rm \
  --env-file /path/to/env.docker \
  -v /path/to/repositories.yaml:/config/repositories.yaml:ro \
  bitbucket-pr-review-mcp:local --check

{
  "mcpServers": {
    "bitbucket-pr-review": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/env.docker",
        "-v", "/path/to/repositories.yaml:/config/repositories.yaml:ro",
        "bitbucket-pr-review-mcp:local"
      ]
    }
  }
}

docker-compose.yaml записывает те же флаги один раз: docker compose run --rm bitbucket-pr-review, читая .env.docker (в gitignore) из этого каталога.

Несколько вещей, которые стоит знать:

• На Windows используйте путь в стиле Windows в -v (d:/path/to/repositories.yaml:/config/...). В Git Bash добавьте префикс MSYS_NO_PATHCONV=1 к команде, иначе путь будет переписан.

• Белый список монтируется, а не встраивается. Он называет репозитории, к которым сервер может обращаться; этот список принадлежит тому, кто запускает образ, а не образу.

• --setup завершается с кодом 2 в контейнере, сообщая, где можно запустить настройку. Ротация токена означает перезапуск с новым.

• Контейнер работает как непривилегированный пользователь, только для чтения, со всеми отброшенными capabilities.

Подключение к общему серверу

Общее развёртывание — несколько человек, один сервер, у каждого своя учётная запись Bitbucket — работает за одним origin. И конечная точка MCP, и Keycloak обслуживаются с него, потому что issuer — это строка, которая должна означать одно и то же в токене, документе обнаружения, браузере и конфигурации.

Ни Claude Desktop, ни Claude Code не обращаются к серверу напрямую через localhost. Пользовательский коннектор Claude загружается инфраструктурой Anthropic, а не вашей машиной, поэтому сервер на вашем ноутбуке недостижим, как бы он ни был настроен. Локальный цикл идёт через mcp-remote: мост stdio, который работает на вашей машине, выполняет поток OAuth в вашем браузере и говорит по HTTP с сервером. Как только у сервера появляется публичный https-адрес, пользовательский коннектор достигает его напрямую, и мост больше не нужен.

Какой client id куда

В realm есть три OAuth-клиента, потому что аутентифицируются три разные вещи, и они не взаимозаменяемы. Использование неправильного терпит неудачу на первом шаге, с Invalid parameter: redirect_uri на странице ошибки Keycloak — которая называет параметр, а не клиента, и это одно и то же сообщение для любой причины.

Разделение следует за тем, куда попадает callback. Callback коннектора — https://claude.ai/api/mcp/auth_callback, на инфраструктуре Anthropic, поэтому этот клиент конфиденциальный, и его секрет живёт там. Callback моста — это порт loopback на чьём-то ноутбуке, поэтому этот клиент вообще не содержит секрета — секрет в файле конфигурации на ноутбуке — это не секрет, и PKCE защищает поток loopback. Регистрация размещённого callback на публичном клиенте передала бы конфиденциальный поток клиенту, который не может ничего хранить, поэтому он не зарегистрирован, и Keycloak отказывает в этом.

Скопируйте .env.example в .env, затем запустите:

cp .env.example .env      # fill in the secrets; the defaults are the loopback stack
docker compose --profile shared up -d

Это поднимет Postgres, Keycloak, nginx и сервер ревью. docker compose --profile shared ps должен показать четыре здоровых контейнера, и http://localhost:8080/mcp должен отвечать 401 с заголовком WWW-Authenticate, называющим область bitbucket:review — отказ неаутентифицированному запросу — это работающая система.

Claude Code

Зарегистрируйте мост один раз, для всех проектов, с -s user:

claude mcp add bitbucket-pr-review -s user -- npx -y mcp-remote http://localhost:8080/mcp 3334 --allow-http --static-oauth-client-info "{\"client_id\":\"bitbucket-pr-review-cli\"}"

-s user записывает его в ключ верхнего уровня mcpServers в ~/.claude.json, который применяется в каждом каталоге. Альтернативы: -s local (только этот проект, также в ~/.claude.json, в разделе projects) и -s project (закоммиченный .mcp.json). Не регистрируйте его более чем в одной области: конфигурации раздельны, область пользователя выигрывает, и та, которую вы редактируете позже, может не быть используемой.

Проверьте:

claude mcp get bitbucket-pr-review

что должно сообщить Scope: User config и Status: ✔ Connected. Сессия подхватывает MCP- серверы при запуске, поэтому уже запущенный Claude Code не увидит только что зарегистрированный сервер, пока не будет перезапущен.

Выдача кому-то учётной записи

В realm поставляется один пользователь, dev / dev-only-not-for-production, который является учётными данными для разработки и говорит об этом. Всем остальным нужна учётная запись в Keycloak, прежде чем они смогут войти — это отдельная вещь от подключения их учётной записи Bitbucket впоследствии, которую они делают сами на /connect.

В консоли администратора. Откройте http://localhost:8080/admin, войдите как bootstrap-администратор (KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD из вашего .env), переключите выбор realm с master на streamstech, затем Users → Add user. Заполните имя пользователя, email, имя и фамилию, отметьте Email verified и создайте. Затем Credentials → Set password и выключите Temporary, если только вы не хотите, чтобы их попросили сменить пароль при первом входе.

Или из командной строки, что проще повторить:

docker exec bitbucket-pr-review-mcp-keycloak-1 /opt/keycloak/bin/kcadm.sh \
  config credentials --server http://localhost:8080 --realm master \
  --user admin --password "$KC_BOOTSTRAP_ADMIN_PASSWORD"

docker exec bitbucket-pr-review-mcp-keycloak-1 /opt/keycloak/bin/kcadm.sh \
  create users -r streamstech \
  -s username=somebody -s email=somebody@example.com -s emailVerified=true \
  -s firstName=Some -s lastName=Body -s enabled=true

docker exec bitbucket-pr-review-mcp-keycloak-1 /opt/keycloak/bin/kcadm.sh \
  set-password -r streamstech --username somebody --new-password 'their-password'

В Git Bash добавьте перед каждой из этих команд MSYS_NO_PATHCONV=1, иначе /opt/keycloak/... будет переписан в путь Windows, и docker exec сообщит, что файл не существует.

Две вещи, которые легко перепутать, и обе приводят к ошибке при входе, а не при создании, с сообщением, которое не указывает на причину:

• Имя и фамилия обязательны. Профиль пользователя Keycloak считает их обязательными, поэтому учетная запись, созданная без них, аутентифицируется с ошибкой invalid_grant: Account is not fully set up. Ничто не предупреждает вас при создании учетной записи.

• kcadm.sh set-password без -t уже является постоянным; передача -t делает его временным и оставляет то же обязательное действие в ожидании.

Никакие роли или членство в группах не нужны. Новая учетная запись автоматически получает default-roles-streamstech, и этого достаточно — этот сервер авторизует по области bitbucket:review, которая запрашивается во время OAuth-потока и на которую дается согласие, а не предоставляется заранее.

Учетные записи хранятся в базе данных Keycloak, которая является томом. Они переживают перезапуски, но не переживают docker volume rm bitbucket-pr-review-mcp_keycloak-db.

Claude Desktop

В Claude Desktop нет команды mcp add; вы редактируете claude_desktop_config.json вручную. Где он находится, зависит от того, как был установлен Claude:

Путь для Store — это тот, который чаще всего подводит людей — установка из Store полностью игнорирует файл %APPDATA%, и редактирование неправильного ничего не меняет без какой-либо ошибки.

{
  "mcpServers": {
    "bitbucket-pr-review": {
      "command": "cmd",
      "args": [
        "/c", "npx",
        "-y", "mcp-remote",
        "http://localhost:8080/mcp",
        "3335",
        "--allow-http",
        "--static-oauth-client-info", "{\"client_id\":\"bitbucket-pr-review-cli\"}"
      ]
    }
  }
}

deploy/claude_desktop_config.example.json содержит то же самое. Две детали там выполняют реальную работу:

• cmd /c перед npx в Windows. Claude Desktop не запускает через оболочку, поэтому голый "command": "npx" разрешается в пакетный файл, чей собственный путь содержит пробел, и всё умирает с ошибкой 'C:\Program' is not recognized as an internal or external command в журнале ниже. На macOS уберите cmd и /c и используйте "command": "npx".

• Порт 3335, а не 3334. Это число — собственный порт loopback моста, и регистрация Claude Code уже использует 3334. Два моста на одном порту означают, что тот, который запускается вторым, не сможет получить свой OAuth-обратный вызов. Realm регистрирует http://127.0.0.1:*/oauth/callback, так что подойдет любой свободный порт.

Перезапустите Claude Desktop — полностью, из трея, так как закрытие окна оставляет его работающим — и проверьте, что он запустился:

tail -f "$LOCALAPPDATA/Packages/Claude_*/LocalCache/Roaming/Claude/logs/mcp-server-bitbucket-pr-review.log"

Proxy established successfully between local STDIO and remote StreamableHTTPClientTransport — это строка, означающая, что мост общается с сервером. Server transport closed unexpectedly означает, что он вместо этого завершился — причина на несколько строк выше.

Первый вызов инструмента затем открывает вход в Keycloak (dev / dev-only-not-for-production в development realm, или учетная запись, которую вы создали выше). После входа вызов инструмента отвечает ссылкой на /connect, где вы подключаете свою учетную запись Atlassian — эта страница также заставляет браузер войти, поэтому ссылку безопасно видеть в транскрипте.

Несколько вещей, которые стоит знать:

• Мост — это публичный OAuth-клиент, без секрета. Секрет клиента в конфигурационном файле на ноутбуке — это не секрет; PKCE — это то, что защищает loopback-поток.

• Его обратный вызов — http://127.0.0.1:3334/oauth/callback — IP-литерал, а не localhost, и /oauth/callback, а не /callback от Claude Code. Realm регистрирует все из них, потому что ошибка приводит к сбою на последнем шаге потока.

• --allow-http обязателен, пока сервер работает на обычном http. Реальное развертывание — это https, и этот сервер отказывается описывать себя через http где-либо, кроме loopback.

• Аргумент 3334 — это собственный порт моста, и realm регистрирует обратный вызов на нем. Два клиента Claude, работающие одновременно через мост, должны использовать разные порты.

• Значения по умолчанию профиля shared — это конфигурация для разработки — bootstrap-администратор, чей пароль находится в docker-compose.yaml, realm с пользователем, чей пароль находится в файле realm, и обычный http на loopback. Каждый из них — это переменная с значением по умолчанию, поэтому реальное развертывание переопределяет их в .env, а не редактирует какой-либо файл. См. docs/deploying-the-shared-server.md.

• Изменение origin требует повторного импорта realm. Realm импортируется один раз, в базу данных Keycloak; --import-realm оставляет существующий realm нетронутым. Удалите этот том по имени — docker volume rm bitbucket-pr-review-mcp_keycloak-db — и никогда не используйте down -v, который заберет с собой хранилище учетных данных.

Управление им

uv run bb-pr-mcp --health
uv run bb-pr-mcp --rotate-key /path/to/new.key

--health сообщает, пригодно ли развертывание для работы — TLS, ключ хранилища, хранилище, список разрешенных, доступен ли сервер авторизации и сколько людей подключено — и завершается с кодом 0 (здоров), 1 (есть на что посмотреть), 2 (это не запустится).

--rotate-key повторно запечатывает все сохраненные учетные данные под новым ключом без повторного включения кого-либо, затем сообщает вам порядок выполнения остальных действий.

Прочтите docs/deploying-the-shared-server.md перед запуском этого где-либо в реальной среде. В нем указано, во что обходится одна компрометация хоста, что больше, чем кажется, и что с этим делать.

Кто подключен, и как снять кого-то

uv run bb-pr-mcp --who
uv run bb-pr-mcp --revoke alice@streamstech.com

--who перечисляет всех, кто подключил учетную запись Bitbucket: непрозрачный идентификатор, электронную почту Atlassian, когда они подключились и когда истекает их токен. Он расшифровывает хранилище, чтобы ответить, а затем выводит всё, кроме одного поля, которое стоит расшифровывать.

--revoke удаляет сохраненные учетные данные одного человека. Он принимает email или достаточную часть непрозрачного идентификатора, чтобы быть однозначным, и отказывается, а не угадывает, когда имя совпадает с двумя людьми. Отзыв вступает в силу при следующем вызове инструмента, в том числе на сервере, который уже запущен — общий сервер читает учетные данные напрямую, а не хранит их, именно для того, чтобы оператор в другом терминале не ждал перезапуска.

Чего он не делает — это та часть, которую стоит прочитать. Три места хранят что-то после ухода кого-то, и эта команда владеет одним из них:

• Здесь. Сохраненные учетные данные удалены.

• Keycloak. Они все еще могут войти и подключить новый токен. Отключите их учетную запись там, чтобы это остановить.

• Atlassian. Их API-токен все еще существует и все еще работает везде. Только они, или администратор Atlassian, могут отозвать его.

Команда говорит все три каждый раз, потому что чек-лист по выходу, который отмечается после первого шага, хуже, чем отсутствие чек-листа.

Ни то, ни другое не является инструментом, и это намеренно: описание pull request не должно иметь возможности уговорить Caller отключить коллегу.

Инструменты

Pull request называется одной строкой: либо URL Bitbucket, либо сокращением workspace/repo/id.

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

Всё ниже имеет рабочее значение по умолчанию. Установите их в окружении или в файле .env, все с префиксом BB_MCP_:

Существуют еще два, и они пусты, пока общее развертывание не завершено — описанная выше установка на устройство не нуждается ни в одном из них, потому что у stdio ровно один вызывающий:

Каждый лимит явно указывается в ответе, когда он срабатывает. Усечение никогда не происходит молча: Caller, который не может отличить усечённый diff от полного, сочтёт недостающую половину просмотренной, исходя из предположения, что с ней всё в порядке.

Разработка

uv run pytest                    # the suite
uv run pytest --cov=src          # with coverage
uv run ruff check src tests      # lint
uv run ruff format src tests     # format

Тесты никогда не обращаются к сети. Точка разделения — это HTTP-транспорт и только он, поэтому защитная проверка, список разрешённых и каждый модуль чтения ответов проверяются как боевой код. В tests/recorded/ хранятся ответы, записанные при работе с реальным pull request — см. docs/architecture.md, почему это важнее, чем кажется.