mcp-bitbucket

Bitbucket Server для AI-агентов и людей рядом с ними. Читайте pull request'ы и их диффы без клонирования, составляйте ревью и публикуйте его с вердиктом, ставьте блокирующие задачи, просматривайте код и коммиты, открывайте, мёржите или отклоняйте pull request'ы — из MCP-клиента, из шелла или из собственного TypeScript.

Только Bitbucket Server / Data Center. Bitbucket Cloud не поддерживается.

Пакеты

Использование инструментов Claude Code / Claude Desktop → mcp. Терминал, скрипты, CI, агенты, выполняющие команды → cli. Создание чего-то другого → core. Они читают одни и те же учётные данные и устанавливаются рядом.

Related MCP server: mcp-server-atlassian-bitbucket

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

• Node.js 18+, pnpm 10+ (corepack enable)

• Персональный токен доступа Bitbucket Server — профиль → Manage Account → HTTP Access Tokens, с чтением репозитория и записью pull request'ов

• Только для bb login (системная связка ключей): sudo apt install -y libsecret-1-0 gnome-keyring. Каждая команда также работает из BITBUCKET_TOKEN.

Установка

pnpm install
pnpm build        # core first, then mcp and cli

Точки входа: packages/mcp/dist/index.js, packages/cli/dist/index.js.

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

MCP-сервер

claude mcp add mcp-bitbucket \
  -e BITBUCKET_URL=https://bitbucket.example.com \
  -e BITBUCKET_TOKEN=your-personal-access-token \
  -- node /absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js

Или в .mcp.json (${VAR} раскрывается Claude Code, поэтому секрет не коммитится):

{
  "mcpServers": {
    "mcp-bitbucket": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "${BITBUCKET_URL}",
        "BITBUCKET_TOKEN": "${BITBUCKET_TOKEN}"
      }
    }
  }
}

HTTP-транспорт вместо stdio: node packages/mcp/dist/index.js --http (порт 3000) или MCP_HTTP_PORT=8080 node …. Маршруты: POST /mcp, GET /mcp (SSE), DELETE /mcp.

CLI bb

pnpm --filter @mcp-bitbucket/cli link --global
bb login          # or export BITBUCKET_URL / BITBUCKET_TOKEN
bb whoami         # proves authentication — `bb ping` only proves reachability
bb pr get 42      # repository comes from the git origin remote

Поверхность команд: packages/cli/README.md или bb --help.

Навык Claude Code

bash packages/skill/scripts/install.sh            # ~/.claude/skills/bitbucket-review
bash packages/skill/scripts/install.sh ./.claude  # project scope

Требуется bb в PATH и разрешимые учётные данные.

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

Переменные окружения, .env в корне репозитория загружается автоматически (cp .env.example .env). MCP-сервер проверяет их при запуске; CLI также принимает --url / --token, которые имеют приоритет над всем.

Лимиты

Каждый числовой предел находится в packages/core/src/operations/caps.ts и может быть переопределён через env: BITBUCKET_DIFF_MAX_CHARS (60000), BITBUCKET_DIFF_HEAD_RATIO (0.6), BITBUCKET_DIFF_CONTEXT_LINES (3), BITBUCKET_DIFF_FETCH_MAX_CHARS (12000000), BITBUCKET_DIFF_CACHE_ENTRIES (4), BITBUCKET_CHANGED_FILES_MAX_ITEMS (1000), BITBUCKET_CHANGED_FILES_STATS_MAX_FILES (500). Усечение никогда не происходит молча — примечание называет параметр и переменную, которая поднимает предел, и перечисляет каждый пропущенный заголовок хунка.

Разрешения

Два независимых ограничителя.

MCP_PERMISSION_MODE — только MCP-сервер. Каждый инструмент классифицируется как read, write или destructive в packages/mcp/src/permissions.ts; запрещённый инструмент скрыт из ListTools и отклоняется при вызове по имени.

CLI его не читает. Развёртывание readonly не останавливает bb review merge.

Белый список репозиториев — обе точки входа. BITBUCKET_ALLOWED_PROJECTS / BITBUCKET_ALLOWED_REPOS принимают разделённые запятыми, точкой с запятой или пробелами шаблоны: PROJ, PROJ/*, PROJ/repo-a. Проверка выполняется внутри общего клиента до открытия любого сокета, поэтому каждый инструмент и каждая команда bb наследуют её. Не задано — значит все репозитории. Регистронезависимо; личные репозитории — проект ~username. Некорректный шаблон отбрасывается, но не расширяется — значение, состоящее только из некорректных шаблонов, не разрешает ничего.

Инструменты

29 MCP-инструментов: 17 чтения, 9 записи, 3 разрушительных. Полные параметры в docs/tools.md.

Примечательные значения по умолчанию

• Разрешённые обсуждения скрыты. get_pull_request_comments / bb comment ls требуют includeResolved (--include-resolved), чтобы показать разрешённые ветки и задачи; ответ сообщает, сколько скрыто. Явный фильтр state переопределяет значение по умолчанию.

• Ревью создаются как черновики, а не публикуются. add_pr_draft_comment / bb review draft сохраняют невидимый комментарий; submit_pr_review публикует все ожидающие комментарии с вердиктом одним уведомлением. pending: false (--no-pending) публикует сразу; discard_pr_draft_review выбрасывает черновик.

• bb ping ≠ аутентификация. /application-properties отвечает 200 анонимно на многих экземплярах. bb whoami — проверка аутентификации.

Разработка

pnpm build | typecheck | test | lint | format | clean
pnpm dev:mcp                 # MCP server from source (tsx)
pnpm cli pr ls               # bb from source
pnpm --filter @mcp-bitbucket/core test

Правило слоёв, которое не даёт адаптерам расходиться:

• core ничего не знает об MCP или CLI — ни MCP SDK, ни yargs, ни stdout. Операции принимают клиент и параметры и возвращают структурированные данные или выбрасывают исключение.

• Адаптеры владеют проверкой ввода и формой вывода — zod и форма результата MCP в mcp, yargs и текст/--json в cli. Ни то, ни другое не протекает в core.

• Сообщения об ошибках пишутся один раз, в core, с плейсхолдерами вроде {projects} / {login}, которые каждый адаптер рендерит в своём словаре — один и тот же сбой говорит модели «используйте list_projects», а вам — «используйте bb project ls».

• Новая возможность — это операция плюс форматтер в core, затем тонкий адаптер в каждом из mcp и cli.

Docker

Образ содержит только MCP-сервер.

docker build -t mcp-bitbucket .
docker run -i --rm -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… mcp-bitbucket
docker run --rm -p 3000:3000 -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… -e MCP_HTTP_PORT=3000 mcp-bitbucket

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

docs/troubleshooting.md. Три самые частые: инструмент отсутствует в списке клиента — значит MCP_PERMISSION_MODE скрыл его (нераспознанное значение скрывает все 29); Refused: … outside the configured repository allowlist — белый список не покрывает этот репозиторий; комментариев меньше, чем в веб-интерфейсе — разрешённые ветки скрыты.

Ограничения

• Только Bitbucket Server; нет Bitbucket Cloud, OAuth/SSO или паролей приложений.

• bb login хранит учётные данные только в системной связке ключей — нет хранилища в открытом виде, нет --password.

• Нет вебхуков или событийного режима; сервер отвечает на вызовы инструментов.

• Диффы — это серверный текст unified diff; встроенные комментарии, привязанные к диффу, не раскрываются.

• search_code требует индекс кода экземпляра: ветка по умолчанию, целые слова, без регулярных выражений.

• MCP_PERMISSION_MODE ограничивает только MCP-сервер; белый список ограничивает оба.