Bitbucket MCP

bitbucket-cli

基于实时 OpenAPI 规范构建的低维护成本 Bitbucket Cloud 工具：为软件工程师提供 CLI，为 AI Agent 提供 MCP 服务，并为 DevSecOps 团队提供 Terraform provider。

重要

https://github.com/FabianSchurig/bitbucket-cli 是规范仓库。 如果你通过 terraform-provider-bitbucket 镜像发现此项目，请在 bitbucket-cli 仓库中关注、加星、提交问题并参与贡献。

从这里开始

受众	最适合的工具	从这里开始
DevSecOps 工程师	Terraform provider	Terraform Registry、生成的 provider 文档、示例：bitbucket_tags
软件工程师 / 计算机科学家	bb-cli	CLI 使用指南
AI Agent / Agent 平台用户	bb-mcp	MCP 使用指南

快速链接

• 规范 GitHub 仓库
• Terraform Registry：FabianSchurig/bitbucket
• 镜像仓库：terraform-provider-bitbucket
• GitHub Releases
• SonarQube Cloud
• 贡献指南

安装

Homebrew（macOS 和 Linux）

通过我们的自定义 tap 安装 CLI 工具时，请添加仓库并明确地信任该 formula，以降低供应链风险：

brew tap FabianSchurig/tap
brew trust --formula FabianSchurig/tap/bitbucket-cli
brew install bitbucket-cli

或者安装 MCP 服务：

brew tap FabianSchurig/tap
brew trust --formula FabianSchurig/tap/bitbucket-mcp
brew install bitbucket-mcp

（注意：如果你之前添加过旧的 cask，可以在运行命令前安全地通过 brew untap fabianschurig/tap 取消添加。）

APT（Debian / Ubuntu）

从最新版本下载 .deb 软件包并安装。支持的架构：amd64、arm64。

TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(dpkg --print-architecture)
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.deb"
sudo dpkg -i "bb-cli_${VERSION}_${ARCH}.deb"

将 bb-cli 替换为 bb-mcp，即可改为安装 MCP 服务。

RPM（Fedora / RHEL / CentOS）

从最新版本下载 .rpm 软件包并安装。支持的架构：amd64、arm64。

TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.rpm"
sudo rpm -i "bb-cli_${VERSION}_${ARCH}.rpm"

将 bb-cli 替换为 bb-mcp，即可改为安装 MCP 服务。

Scoop（Windows）

scoop bucket add bitbucket https://github.com/FabianSchurig/scoop-bucket
scoop install bb-cli
scoop install bb-mcp

Winget（Windows）

winget install FabianSchurig.bb-cli
winget install FabianSchurig.bb-mcp

安装脚本

curl -fsSL https://raw.githubusercontent.com/FabianSchurig/bitbucket-cli/main/install.sh | sh

有关版本选择、二进制文件选项（bb-cli、bb-mcp 或 all）和自定义安装目录，请参阅 install.sh 选项。

其他方法

方法	命令
Go 安装	go install github.com/FabianSchurig/bitbucket-cli/cmd/bb-cli@latest
Docker	docker pull ghcr.io/fabianschurig/bitbucket-cli:latest
下载二进制文件	GitHub Releases

完整安装详情请参阅 CLI 使用指南 和 MCP 使用指南。

本项目的定位

此代码仓库通过基于实时 Bitbucket OpenAPI 规范生成大部分内容，让 Bitbucket Cloud 工具保持易于维护。

• 一份 API 描述，三种面向用户的工具：CLI、MCP 和 Terraform 都来自同一套架构生成流程。
• 精简的手写运行时：身份验证、分发、输出和 Terraform 运行时保持通用，而不是为每个端点添加专用代码。
• 快速采用规范：新的 Bitbucket 端点通过生成流程接入，无需大规模手动重写。
• 以维护为先的设计：主要开发工作投入共享生成器和运行时，而非重复的端点代码。
• 同样支持内部／未公开端点：对于 Bitbucket 公共 OpenAPI 规范中未包含的端点（例如仅通过 https://bitbucket.org/!api/internal/... 暴露的项目级分支限制端点），可以在 schema/ 下手动编写架构。生成器和运行时会以相同方式处理它们——架构路径可以使用绝对 URL，分发器会原样传递这些路径。

架构

flowchart LR
    A[Live Bitbucket OpenAPI spec] --> B[enrich_spec.py]
    B --> C[partition_spec.py]
    C --> D[schema/*-schema.yaml]
    D --> E[oapi-codegen models]
    D --> F[CLI generator]
    D --> G[MCP generator]
    D --> H[Terraform generator]
    E --> I[Shared generated types]
    F --> J[bb-cli]
    G --> K[bb-mcp]
    H --> L[terraform-provider-bitbucket]
    I --> J
    I --> K
    I --> L
    M[Hand-written runtime\nauth, dispatch, output, MCP handler, TF runtime] --> J
    M --> K
    M --> L

具体来说：

• CLI 将 Bitbucket 操作作为终端命令提供。
• MCP 将相同操作作为工具调用提供给 AI Agent。
• Terraform 将操作组映射为通用资源和数据源。
• 手写代码有意保持精简；端点覆盖由生成代码处理。

CI 流水线

flowchart TD
    A[push / pull_request] --> B[ci.yml]
    A --> C[terraform-tests.yml]
    D[schedule / manual] --> E[schema-sync.yml]
    E --> F[Fetch live spec]
    F --> G[Regenerate code and docs]
    G --> H[Build and test]
    H --> I[Tag new version]
    I --> J[release.yml]
    J --> K[docker.yml]
    I --> L[terraform-release.yml]
    K --> M[Publish to MCP Registry]

• ci.yml：构建、执行 lint 和 vet、运行 Go 测试，并将分析结果发送到 SonarQube Cloud。
• terraform-tests.yml：运行基于模拟的 Terraform 验收测试和 terraform test 测试套件，并在存在凭据时运行真实 API 测试。当前真实 API 测试覆盖的端点列表，请参阅 docs/e2e-coverage.md。
• schema-sync.yml：每日／手动同步实时 Bitbucket 规范、重新生成生成的构件、重建文档、运行所有测试，并在架构发生变化时标记一个版本。
• release.yml：通过 GoReleaser 发布带标签的二进制版本。
• docker.yml：为 bb-cli 和 bb-mcp 构建多架构容器镜像，将其推送到 GHCR，发布其 SBOM 和 CVE 报告（参见供应链：SBOM 和 CVE 报告），并将 bb-mcp 服务发布到 MCP Registry。
• terraform-release.yml：将带标签的源代码同步到 terraform-provider-bitbucket，并发布 Terraform 提供程序版本。

Schema 同步安全性

实时 OpenAPI 文档被视为输入，而非有权因暂时遗漏而删除正常 API 分组的权威来源。以下三种机制可防止每日同步破坏已发布的接口或同步流程本身：

• 保留分组：当某个分组提取后没有路径时，partition_spec.py 会保留该分组现有的非空 Schema；真正为空或新建的分组仍会照常写入。
• 稳定的 operationId：ID 会记录在已提交的锁定文件 schema/operation-ids.json 中，以 "<method> <path>" 为键。某个操作的 ID 永远不变，已移除操作的 ID 也会继续保留——因此，同级端点永远无法继承某个 ID，悄然重命名已发布的 CLI 命令、MCP 工具或 CRUDConfig 引用。
• 保留操作：Atlassian 会定期从已发布的规范中移除已弃用但仍可用的端点。为避免在自动补丁版本发布时丢弃命令，partition_spec.py 会将此类操作从已提交的 Schema 原样沿用，并标注 x-bb-cli-retained: true，以便 Schema 差异准确显示上游停止发布的内容。彻底弃用某个操作需要有意为之：将其从 schema/*-schema.yaml 中删除，随后不变量测试会标记仍引用它的任何手动维护映射（例如 CRUDConfig 中的映射）。

internal/tfprovider/acceptance_test.go 中的验收测试由人工编写，绝不会因 Schema 生成而删除。生成的 Terraform 测试夹具会根据保留的资源分组重新生成；提交或发布任何更改前，Schema 同步构建和测试门禁（包括模拟 Terraform 验收测试套件）都必须通过。生成的真实 API 覆盖率报告可以直观呈现分组覆盖缺失之处，无需手动记录。

供应链：SBOM 和 CVE 报告

每个发布的容器映像都附带一份标准格式的软件物料清单和漏洞报告。两者均基于推送到 GHCR 的确切映像摘要生成。

工件	格式	获取位置
映像 SBOM	SPDX 2.3 JSON	对应的 GitHub Release 中的 sbom-bitbucket-cli.spdx.json / sbom-bitbucket-mcp.spdx.json，或作为映像本身的签名证明
映像 CVE 报告	Grype JSON + 纯文本表格	对应的 GitHub Release 中的 cves-bitbucket-cli.{json,txt} / cves-bitbucket-mcp.{json,txt}
源码 SBOM	SPDX JSON	由 release.yml 附加到 GitHub Release（涵盖 git 标签，而非映像）

SBOM 还会作为与摘要绑定的签名 GitHub 证明附加到映像，因此使用者无需访问此仓库即可验证并获取它：

gh attestation verify oci://ghcr.io/fabianschurig/bitbucket-mcp:latest --owner FabianSchurig
gh attestation download oci://ghcr.io/fabianschurig/bitbucket-mcp:latest --owner FabianSchurig

运行时映像基于 FROM scratch 构建，仅包含静态二进制文件和 CA 证书，因此 SBOM 有意保持精简，也没有需要修补的操作系统软件包。

漏洞扫描结果还会上传到 GitHub 代码扫描，供维护者查看（类别为 docker-bitbucket-cli 和 docker-bitbucket-mcp）；此外，security.yml 中的 govulncheck 会检查 Go 模块树。

与 DrFaust92/terraform-provider-bitbucket 的区别

方面	DrFaust92/terraform-provider-bitbucket	FabianSchurig/bitbucket
维护模式	手工编写的提供程序资源	主要根据实时 Bitbucket OpenAPI 规范生成
范围	仅 Terraform 提供程序	在一个权威仓库中集成 Terraform 提供程序、CLI 和 MCP 服务
API 覆盖模式	精选的类型化资源	通过分组的通用资源／数据源广泛覆盖端点
更新流程	针对每项资源手动开发功能	架构同步流水线重新生成代码和文档
资源形式	针对具体资源的类型化字段	通用参数、响应字段和原始 API 响应
最适用场景	规范明确的 Terraform 工作流	希望快速覆盖 Bitbucket API，并在 Terraform、shell 和 AI Agent 之间共享工具的团队

本项目专注于广泛覆盖、易于维护，以及为不同接口提供共享基础设施。如果你想要高度手工建模的 Terraform 体验，DrFaust92 提供程序可能会更熟悉。如果你希望通过一条统一维护的流水线，让 Terraform、CLI 和 MCP 与 Bitbucket Cloud 保持同步，那么本仓库正是为此设计的。

文档导航

先通过首页的简短指南开始使用，然后根据需要切换到相应接口的详细文档。

• CLI：docs/cli.md
• MCP：docs/mcp.md
• Terraform 提供程序文档：docs/index.md 和 Terraform Registry 文档
• 真实 API 端到端测试覆盖情况：docs/e2e-coverage.md — 自动生成的列表，列出哪些资源组由 TestAccRealAPI_* 测试覆盖，以及哪些仍缺少覆盖。

docs/ 下的 Terraform 文档由程序生成。根目录 README 专注于项目概览、链接、架构、维护方式和贡献入口。

维护与贡献

• 修改生成器或运行时代码前，请阅读 CONTRIBUTING.md。
• 不要手动编辑生成的文件；应修复生成器或架构源文件。
• 优先进行能改进共享流水线或所有端点手写运行时的更改。
• 请在权威的 bitbucket-cli 仓库中提交问题和拉取请求。