@droplinkperformance/bitbucket-mcp-server

Провайдер-независимый, ориентированный на AI-ревью Model Context Protocol (MCP) сервер для Bitbucket Cloud.

Основная ценность этого сервера — AI-ревью кода и анализ пулл-реквестов, а не CRUD-операции с Bitbucket API. Каждая ключевая зависимость (доступ к SCM, кэш, хранение токенов, rate limiting, LLM, события) скрыта за провайдер-независимым интерфейсом, чтобы та же бизнес-логика в дальнейшем могла работать с GitHub / GitLab / Azure DevOps и OpenAI / Anthropic / Gemini / Bedrock без изменений в use-cases, агентах или доменных контрактах.

Статус: Фаза 1. См. Roadmap.

Возможности (Фаза 1)

• Два транспорта: stdio (Cursor / Claude Desktop) и Streamable HTTP (Node http, для удалённой работы / продакшена).

• Автоматически обнаруживаемые инструменты через ToolRegistry — без ручной регистрации.

• Явный BitbucketContext (workspace + опциональный repository) в каждом инструменте — готовность к нескольким workspace.

• Устойчивый BitbucketClient: подстановка авторизации, автоматическая пагинация, retry/backoff, обработка rate limit, кэширование, маскирование секретов.

• Две стратегии аутентификации: OAuth 2.0 (Authorization Code, с сохранением ротации refresh-токенов) и Bearer token.

• AI-ревью кода (analyze_pull_request) на базе CodeReviewAgent, который разбивает большие PR на части и возвращает стандартный ReviewResult.

• Подключаемые LLM-провайдер (OpenAI / Anthropic / Gemini / Bedrock), кэш (memory / Redis) и хранилище токенов (file / memory / Redis).

Инструменты

Все входные параметры инструментов принимают workspace (необязателен, если задан BITBUCKET_DEFAULT_WORKSPACE) и, где применимо, repository.

Related MCP server: Atlassian Bitbucket MCP Server

Архитектура

src/
  index.ts            entry: chooses transport
  container.ts        composition root (the only place wiring concretes)
  mcp/                McpServer + ToolRegistry (auto-discovery) + transports
  tools/              thin MCP adapters (*.tool.ts) -> call exactly one use-case
  application/        use-cases (CQRS-ish: command|query) with Input/Output DTOs
  agents/             autonomous workflows implementing Agent<TInput,TOutput>
  domain/             provider-agnostic types, repository contracts, ReviewResult
  repositories/bitbucket/  Bitbucket implementations of the contracts
  clients/bitbucket/  resilient REST client
  auth/               AuthProvider (+ token/oauth) and TokenStore implementations
  cache/              CacheProvider (+ memory/redis)
  ratelimit/          RateLimitStrategy (+ bitbucket)
  llm/                LlmProvider (+ openai/anthropic/gemini/bedrock)
  events/             EventBus (+ in-memory)
  services/           reusable services (masking, chunking)
  telemetry/          OpenTelemetry bootstrap + metrics
  infrastructure/     config, logger, http, attachments
  shared/             errors, result envelope, http-status, BitbucketContext

Поток: tool -> use-case -> (agent | repository contract) -> repositories/bitbucket -> BitbucketClient. Агенты также могут использовать LlmProvider и EventBus. Инструменты никогда не содержат бизнес-логики.

Требования

• Node.js 23+

Установка

Опубликован как @droplinkperformance/bitbucket-mcp-server.

npx -y @droplinkperformance/bitbucket-mcp-server

Из исходников:

npm install
npm run build

Релиз

Слияния в main запускают .github/workflows/release.yml: тесты, сборка, затем semantic-release. Версия и публикация в npm происходят только когда слияние включает Conventional Commits:

Остальные сообщения пропускают публикацию. Требуется GitHub-секрет NPM_TOKEN (npm Automation token для организации droplinkperformance).

После успешного npm-релиза тот же workflow публикует метаданные в MCP Registry как io.github.droplinkperformance/bitbucket-mcp-server (OIDC, без дополнительного секрета). github.com/mcp синхронизируется из этого реестра; если сервер не появился, напишите на partnerships@github.com.

Чтобы остаться на 0.x для первого релиза, поставьте тег на текущий коммит (git tag v0.1.0 && git push origin v0.1.0) до первого conventional-слияния; иначе semantic-release начнёт с 1.0.0.

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

Скопируйте .env.example в .env и заполните значения. Загрузите его встроенным флагом Node:

node --env-file=.env dist/index.js

Ключевые переменные:

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

Bearer (OAuth access token): укажите только BITBUCKET_ACCESS_TOKEN (не ATATT-токены).

API token (рекомендуется, ATATT…): укажите BITBUCKET_ACCESS_TOKEN и BITBUCKET_EMAIL (email вашего Atlassian-аккаунта: Bitbucket → Personal settings → Email aliases). API-токены используют HTTP Basic auth, а не Bearer.

App password (устаревший способ, до июня 2026): укажите BITBUCKET_ACCESS_TOKEN и BITBUCKET_USERNAME (ваше имя пользователя Bitbucket).

OAuth 2.0 (Authorization Code): укажите BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET. Токены сохраняются в настроенном TOKEN_STORE; Bitbucket ротирует refresh-токены, и сервер сохраняет новый при каждом обновлении. Для headless-запуска укажите ранее полученный BITBUCKET_REFRESH_TOKEN.

Используемые OAuth-эндпоинты Bitbucket: authorize https://bitbucket.org/site/oauth2/authorize, token https://bitbucket.org/site/oauth2/access_token. URL authorize можно построить через OAuthProvider.buildAuthorizeUrl(), а полученный ?code= обменять через OAuthProvider.loginWithCode(code).

LLM-провайдер

Укажите LLM_PROVIDER и соответствующий ключ:

LLM_PROVIDER=openai      # OPENAI_API_KEY
LLM_PROVIDER=anthropic   # ANTHROPIC_API_KEY
LLM_PROVIDER=gemini      # GEMINI_API_KEY
LLM_PROVIDER=bedrock     # AWS creds + BEDROCK_MODEL_ID (needs @aws-sdk/client-bedrock-runtime)

ioredis (Redis-провайдеры) и @aws-sdk/client-bedrock-runtime (Bedrock) опциональны и загружаются лениво — нужны только при выборе соответствующих провайдеров.

Запуск

stdio

MCP_TRANSPORT=stdio node --env-file=.env dist/index.js

Streamable HTTP

MCP_TRANSPORT=http HTTP_PORT=3000 node --env-file=.env dist/index.js
# health:   GET  http://localhost:3000/health
# endpoint: POST http://localhost:3000/mcp

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Cursor

~/.cursor/mcp.json (или проектный .cursor/mcp.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BITBUCKET_ACCESS_TOKEN": "ATATT-your-api-token",
        "BITBUCKET_EMAIL": "you@company.com",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_ACCESS_TOKEN": "your-token",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Разработка

npm run dev          # tsx watch (stdio)
npm run typecheck
npm run lint
npm test
npm run test:coverage

Roadmap

• Фаза 1 (этот релиз): аутентификация, абстракции, BitbucketClient, автообнаружение инструментов, PR-инструменты, analyze_pull_request.

• Фаза 2: Pipelines + полные постраничные логи, агент pipeline-investigator, auto_review_pull_request (dry-run / публикация инлайн-комментариев).

• Фаза 3: Остальной CRUD — репозитории, коммиты, ветки, теги, issues, workspace, участники, поиск.

• Фаза 4: analyze_dotnet_pull_request (агент dotnet-review), продвинутые агенты, сценарии автоматизации.

• Фаза 5: Docker, Compose, Helm, руководство по продакшен-деплою.

Лицензия

MIT