星战科技xingzhan.cloud
返回市场
比特桶-MCP-云

比特桶-MCP-云

作者：jhonymiler2 星标更新：2025-07-07
安装使用来源：spider==github.com

项目介绍

Bitbucket Cloud MCP Server

PyPI 版本 Python 许可证: MIT 测试

一个用于与 Bitbucket Cloud API 平滑集成的生产就绪型模型上下文协议（MCP）服务器。该服务器按照企业级质量标准构建，通过标准化的 MCP 接口提供对 Bitbucket Cloud 功能的全面访问。

🌟 高亮功能

  • ✅ 完整的 Bitbucket Cloud API 覆盖 - 实现所有关键特性
  • ✅ 生产就绪 - 全面的错误处理、日志记录和类型安全
  • ✅ 多种安装方法 - PyPI、直接执行或开发模式
  • ✅ Claude Desktop 集成 - 准备用于 AI 助手工作流
  • ✅ 全面测试 - 包含自动化 CI/CD 的综合测试套件
  • ✅ 干净架构 - 遵循 SOLID 原则的模块化设计

🛠️ 特性 (15 工具)

🎯 项目及仓库管理

  • list_projects - 列出工作区中所有可访问的项目
  • list_repositories - 按工作区或项目列出仓库
  • list_commits - 浏览提交历史并使用过滤选项

🔄 拉取请求生命周期

  • list_pull_requests - 列出带有状态过滤的拉取请求 (OPEN, MERGED, DECLINED)
  • get_pull_request - 获取详细的拉取请求信息
  • create_pull_request - 创建新的拉取请求并指定审阅者
  • update_pull_request - 更新拉取请求标题和/或描述
  • approve_pull_request - 批准拉取请求
  • decline_pull_request - 拒绝拉取请求
  • merge_pull_request - 合并已批准的拉取请求并选择合并策略

💬 评论系统

  • list_pull_request_comments - 列出所有拉取请求评论
  • create_pull_request_comment - 添加通用评论
  • create_pull_request_inline_comment - 添加行特定代码评论

📊 代码分析

  • get_pull_request_diff - 获取完整的代码审查差异
  • get_pull_request_diffstat - 获取更改摘要 (文件、添加/删除的行数)

🚀 安装与使用

方法 1：通过 uvx 直接执行 (推荐)

# 不需要安装 - 直接从 PyPI 运行
uvx bitbucket-mcp-cloud

# 对于支持的 MCP 工具
mcp run bitbucket-mcp-cloud

方法 2：全局安装

# 全局安装
pip install bitbucket-mcp-cloud

# 运行服务器
bitbucket-mcp-cloud

方法 3：开发模式

# 克隆并设置开发环境
git clone https://github.com/jhonymiler/Bitbucket-MCP-Cloud.git
cd Bitbucket-MCP-Cloud

# 使用 uv (推荐)
uv sync
uv run server.py

# 或使用 pip
pip install -e .
python server.py

方法 4：MCP 工具集成

# 使用 MCP CLI
mcp run server.py

# 用于开发和测试
uv run mcp dev server.py

📋 先决条件

  • Python 3.10+
  • 一个 Bitbucket Cloud 账户
  • 配置好的 Bitbucket 应用密码

⚙️ 设置

1. 创建 Bitbucket 应用密码

  1. 访问：账户设置 > 应用密码
  2. 点击“创建应用密码”
  3. 选择所需的权限：
    • 仓库：读、写
    • 拉取请求：读、写
    • 项目：读

2. 配置环境变量

# 选项 1：使用 .env 文件 (开发时)
cp .env.example .env
# 编辑 .env 文件以包含您的凭据

# 选项 2：导出环境变量
export BITBUCKET_USERNAME=your_username
export BITBUCKET_TOKEN=your_app_password
export BITBUCKET_DEFAULT_WORKSPACE=your_workspace

3. Claude Desktop 集成

在您的 Claude Desktop 配置 (~/Library/Application Support/Claude/claude_desktop_config.json) 中添加：

{
  "mcpServers": {
    "bitbucket": {
      "command": "uvx",
      "args": ["bitbucket-mcp-cloud"],
      "env": {
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_TOKEN": "your_app_password",
        "BITBUCKET_DEFAULT_WORKSPACE": "your_workspace"
      }
    }
  }
}

🔧 工具使用示例

项目和仓库

# 列出项目
await list_projects(workspace="my-workspace", limit=25)

# 列出所有仓库
await list_repositories(workspace="my-workspace")

# 列出特定项目的仓库
await list_repositories(workspace="my-workspace", project="PROJ")

拉取请求

# 列出打开的 PR
await list_pull_requests(repository="my-repo", state="OPEN")

# 获取 PR 详情
await get_pull_request(repository="my-repo", pr_id=123)

# 创建新的 PR
await create_pull_request(
    repository="my-repo",
    title="新功能",
    source_branch="feature/new-feature",
    target_branch="main",
    description="实现新功能 X"
)

# 更新 PR 描述
await update_pull_request(
    repository="my-repo",
    pr_id=123,
    description="更新描述，提供更多细节"
)

# 批准并合并 PR
await approve_pull_request(repository="my-repo", pr_id=123)
await merge_pull_request(repository="my-repo", pr_id=123, merge_strategy="squash")

评论和代码审查

# 在特定行上创建内联评论
await create_pull_request_inline_comment(
    repository="my-repo",
    pr_id=123,
    content="这个函数可以优化",
    filename="src/main.py",
    line_number=42
)

# 获取差异以进行分析
diff_text = await get_pull_request_diff(repository="my-repo", pr_id=123)

# 获取更改摘要
diffstat = await get_pull_request_diffstat(repository="my-repo", pr_id=123)

🏗️ 架构

bitbucket-mcp-cloud/
├── server.py              # 主 MCP 服务器 (入口点)
├── src/
│   ├── models.py          # Pydantic 模型以确保类型安全
│   ├── utils.py           # 工具函数和日志记录
│   └── __init__.py
├── tests/                 # 综合测试套件
│   └── test_bitbucket_mcp.py
├── pyproject.toml         # 项目配置
├── .env.example          # 配置模板
├── .github/
│   └── workflows/
│       └── publish.yml   # CI/CD 管道
└── README.md             # 此文档

关键组件

  • BitbucketCloudClient: 异步 HTTP 客户端，具有全面的 API 覆盖
  • FastMCP: 自动生成工具定义的 MCP 服务器
  • Pydantic 模型: 所有 API 响应的类型安全数据结构
  • 详细日志记录: 详细的操作跟踪和调试
  • 错误处理: 使用适当的 HTTP 状态码的健壮错误处理

🧪 测试

# 运行所有测试
uv run pytest

# 运行带有覆盖率报告的测试
uv run pytest --cov=src --cov-report=html

# 运行特定的测试类别
uv run pytest tests/test_bitbucket_mcp.py::TestMCPTools -v

# 类型检查
uv run mypy server.py src/

# 代码格式化
uv run black server.py src/ tests/

🔒 安全特性

  • 安全认证: 使用 Bitbucket 应用密码 (无需 OAuth 复杂性)
  • 输入验证: 使用 Pydantic 模型进行全面验证
  • 错误处理: 清理错误消息 (无凭证泄露)
  • 速率限制意识: 尊重 Bitbucket API 的速率限制
  • 仅 HTTPS: 所有通信加密

📊 质量保证

  • 类型安全: 使用 mypy 验证的完整类型注解
  • 代码质量: 使用 Black 格式化和全面的代码检查
  • 测试: 覆盖所有主要功能的 17 个测试案例
  • CI/CD: 自动测试和 PyPI 发布
  • 文档: 详尽的文档字符串和示例

🔗 API 参考

此 MCP 服务器实现了完整的 Bitbucket Cloud REST API v2.0。涵盖的关键 API 端点包括：

  • /workspaces/{workspace}/projects - 项目管理
  • /repositories/{workspace} - 仓库操作
  • /repositories/{workspace}/{repo}/pullrequests - 拉取请求生命周期
  • /repositories/{workspace}/{repo}/commits - 提交历史
  • /pullrequests/{pr_id}/comments - 评论系统
  • /pullrequests/{pr_id}/diff - 代码分析

🤝 贡献

  1. 分叉仓库
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 运行测试 (uv run pytest)
  4. 提交更改 (git commit -m '添加神奇功能')
  5. 推送到分支 (git push origin feature/amazing-feature)
  6. 打开拉取请求

开发设置

# 克隆并设置
git clone https://github.com/jhonymiler/Bitbucket-MCP-Cloud.git
cd Bitbucket-MCP-Cloud
uv sync --extra dev

# 运行质量检查
uv run pytest
uv run mypy server.py src/
uv run black --check server.py src/ tests/

📝 更改日志

v1.3.5 (最新)

  • ✅ 重新组织包以优化 PyPI 发布
  • ✅ 根目录中的 server.py 和条件导入
  • ✅ 测试并运行所有执行方法
  • ✅ 增强的构建系统和 CI/CD
  • ✅ 生产就绪的包结构

v1.3.4

  • ✅ 服务器正确包含在 PyPI 轮子中
  • ✅ 所有执行方法正常工作 (uvx, pip, 开发)
  • ✅ 完整的测试覆盖
  • ✅ Claude Desktop 集成准备就绪

v1.3.x 系列

  • ✅ 完整的 Bitbucket Cloud API 实现
  • ✅ 全面的错误处理和日志记录
  • ✅ 使用 mypy 验证的类型安全
  • ✅ 生产就绪架构

📄 许可证

MIT 许可证 - 详情见 LICENSE 文件。

🆘 支持

🔗 相关链接

为 MCP 社区制作 ❤️