mcpbitbucket (Ayushh1023)

比特桶MCP服务器

使用FastMCP构建的模型上下文协议（MCP）服务器，提供对Bitbucket存储库和代码库的访问。

特性

• 认证：使用电子邮件和个人访问令牌通过Bitbucket进行安全身份验证
• 工作空间管理：列出并访问Bitbucket工作区
• 存储库访问：浏览支持分页的存储库，并从所有工作区获取
• 代码库探索：获取完整的存储库结构和文件内容
• 文件操作：检索特定文件内容并列出所有文件
• 导出功能：将代码库结构保存为JSON文件
• 优化架构：内部函数阻止工具间调用，并允许代码重用

设置

1.安装依赖项

pip install -r requirements.txt

2.配置身份验证

创建一个 .env 使用您的Bitbucket凭据在项目根目录中创建文件：

BITBUCKET_TOKEN=your_bitbucket_token_here
BITBUCKET_EMAIL=your_bitbucket_email@example.com

要获取您的Bitbucket代币：

1. 首选 Bitbucket应用程序密码
2. 点击“创建应用密码”
3. 为其命名（例如，“MCP服务器”）
4. 选择权限：“帐户读取”、“存储库读取”
5. 复制生成的令牌

3.MCP配置

将此添加到您的MCP客户端配置中（例如。， mcp_config.json):

{
  "mcpServers": {
    "bitbucket-server": {
      "command": "python",
      "args": ["bitbucket_mcp_server.py"],
      "env": {
        "BITBUCKET_TOKEN": "your_bitbucket_token_here",
        "BITBUCKET_EMAIL": "your_bitbucket_email@example.com"
      }
    }
  }
}

可用工具

1. authenticate_user

使用您的电子邮件和令牌通过Bitbucket进行身份验证。

参数：

• email （字符串，可选）：您的Bitbucket电子邮件地址。如果没有提供，将使用配置的BITBUCKET_EMAIL。

退货： 用户信息和身份验证状态

2. get_workspaces

获取用户有权访问的工作区列表。

退货： 包含详细信息的工作区列表

3. get_repositories

获取存储库列表。

参数：

• workspace （可选字符串）：工作区slug（如果未提供，则从所有工作区获取存储库）
• page_size （int）：每页存储库数量（默认值：50）

退货： 从所有工作区获取时包含元数据和工作区详细信息的存储库列表

4. get_all_repositories_with_workspaces

从所有工作区获取包含详细工作区信息的存储库。

参数：

• page_size （int）：每页每个工作区的存储库数量（默认值：50）

退货： 按工作区组织的存储库的详细信息

5. get_repository_branches

从存储库中获取分支列表。

参数：

• workspace （string）：工作区名称/slug
• repo_slug （string）：存储库段塞

退货： 包含详细信息、提交信息和默认分支标识的分支列表

6. get_repository_codebase

获取存储库的完整代码库结构和内容。

参数：

• workspace （string）：工作区名称/slug
• repo_slug （string）：存储库段塞
• branch （string）：分支名称（默认值：'main'）
• path （string）：存储库中的路径（默认：root）
• max_items （可选int）：要返回的最大文件/目录数（用于分页）

退货： 包含文件内容的完整存储库结构，或者如果存在多个分支但未指定特定分支，则列出可用分支

7. get_repository_codebase_paginated

从存储库代码库中获取有限数量的文件/目录（分页）。

参数：

• workspace （string）：工作区名称/slug
• repo_slug （string）：存储库段塞
• max_items （int）：要返回的最大文件/目录数（分页所需）
• branch （string）：分支名称（默认值：'main'）
• path （string）：存储库中的路径（默认：root）

退货： 文件内容有限的存储库结构，或者如果存在多个分支但未指定特定分支，则列出可用分支

8. get_specific_file_content

从存储库中获取特定文件的内容。

参数：

• workspace （string）：工作区名称/slug
• repo_slug （string）：存储库段塞
• file_path （string）：存储库中文件的路径
• branch （string）：分支名称（默认值：'main'）

退货： 文件内容和元数据

9. get_repository_files_list

获取存储库中所有文件的列表（不含内容）。

参数：

• workspace （string）：工作区名称/slug
• repo_slug （string）：存储库段塞
• branch （string）：分支名称（默认值：'main'）
• path （string）：存储库中的路径（默认：root）

退货： 分别列出所有文件和代码文件

9. get_pull_requests

从存储库获取拉取请求。

参数：

• workspace （string）：工作区名称/slug
• repo_slug （string）：存储库段塞
• state （字符串）：PR状态（打开、合并、取消、覆盖）-默认值：打开
• page_size （int）：每页PR数（默认值：50）

退货： 包含详细信息的拉取请求列表

10. get_pull_request_files

获取在拉取请求中更改的文件。

参数：

• workspace （string）：工作区名称/slug
• repo_slug （string）：存储库段塞
• pr_id （int）：拉取请求ID

退货： PR中更改的文件列表，包括更改详细信息和分类

11. find_repository

在所有可访问的工作区中按名称搜索存储库。

参数：

• repo_name （string）：要搜索的存储库名称或slug（不区分大小写）
• page_size （int）：每页每个工作区的存储库数量（默认值：50）

退货： 具有工作区详细信息的匹配存储库列表

12. search_pull_requests

使用描述性查询按标题搜索拉取请求。

参数：

• workspace （string，可选）：工作区名称/slug（如果提供了repo_name，则可选）
• repo_slug （string，可选）：存储库slug（如果提供了repo_name，则可选）
• repo_name （字符串，可选）：跨工作区搜索的存储库名称（如果提供了工作区和repo_slug，则可选）
• search_query （string）：搜索查询以匹配PR标题（不区分大小写）
• state （字符串）：PR状态（打开、合并、取消、覆盖）-默认值：打开
• page_size （int）：每页PR数（默认值：50）

退货： 将搜索查询与其ID和内容匹配的拉取请求列表

13. get_pull_request_details

按ID获取特定拉取请求的全面详细信息。

参数：

• workspace （string，可选）：工作区名称/slug（如果提供了repo_name，则可选）
• repo_slug （string，可选）：存储库slug（如果提供了repo_name，则可选）
• repo_name （字符串，可选）：跨工作区搜索的存储库名称（如果提供了工作区和repo_slug，则可选）
• pr_id （int）：拉取请求ID

退货： 全面的拉取请求详细信息，包括：

• 基本公关信息（标题、描述、状态、日期）
• 作者和参与者信息
• 源和目标分支详细信息
• 审阅者及其审批状态
• 文件随更改统计信息而更改
• 评论和活动
• 链接和元数据

14. save_codebase_to_file

将代码库结构保存为JSON文件。

参数：

• workspace （string）：工作区名称/slug
• repo_slug （string）：存储库段塞
• filename （string）：要保存到的本地文件名
• branch （string）：分支名称（默认值：'main'）
• path （string）：存储库中的路径（默认：root）
• max_items （可选int）：要保存的最大文件/目录数（用于分页）

退货： 成功状态和文件信息

用法示例

1. 启动服务器：

   python bitbucket_mcp_server.py

1. 从您的MCP客户端连接 （例如，克劳德桌面、光标）

1. 使用工具：

- 首次身份验证（如果配置可用，将使用电子邮件） - 获取您的工作空间 - 浏览存储库（默认情况下现在从所有工作区获取） - 探索代码库 - 检索特定文件

架构优化

服务器已通过以下改进进行了优化：

内部功能

• _authenticate_internal()：其他功能使用的内部身份验证功能
• _get_workspaces_internal()：内部工作区提取功能
• _get_repositories_from_workspace_internal()：为特定工作区获取内部存储库
• _get_user_repositories_internal()：内部用户存储库获取
• _find_repository_across_workspaces_internal()：跨所有工作区的内部存储库搜索
• _get_repository_branches_internal()：内部分支取数功能
• _get_repository_codebase_internal()：获取内部代码库结构
• _get_specific_file_content_internal()：内部文件内容获取
• _get_repository_files_list_internal()：获取内部文件列表
• _get_pull_requests_internal()：内部拉取请求获取
• _search_pull_requests_internal()：按标题搜索内部拉取请求
• _get_pull_request_files_internal()：内部拉取请求文件更改获取
• _get_pull_request_details_internal()：内部综合拉取请求详细信息获取

益处

• 无工具间调用：内部函数阻止MCP工具调用其他工具
• 代码重用：共同功能通过内部功能共享
• 更好的错误处理：所有功能的一致错误处理
• 自动身份验证：如果配置了凭据，函数可以自动进行身份验证
• 增强的存储库获取: get_repositories() 现在，当没有提供特定工作区时，从所有工作区获取
• 存储库发现：在所有可访问的工作区中按名称搜索存储库
• 分行管理：用于获取存储库分支和智能分支选择的新工具
• 拉取请求管理：用于获取PR、按标题搜索和分析文件更改的综合工具
• PR详细信息：获取完整的拉取请求信息，包括审阅者、参与者、更改的文件、评论和活动
• 代码库分页：支持限制返回的文件/目录数量以提高性能

安全说明

• 将您的Bitbucket令牌和电子邮件安全地存储在环境变量中
• 从不将令牌提交到版本控制
• 使用具有最低所需权限的应用程序密码
• 服务器在会话期间保持身份验证状态
• 电子邮件可以配置一次，并在会话中重复使用

故障排除

身份验证问题

• 确保您使用的电子邮件地址正确
• 验证您的令牌是否具有所需的权限
• 检查您的令牌是否已过期

存储库访问问题

• 确保您有权访问工作区/存储库
• 验证工作区段块和存储库段块是否正确
• 检查存储库是否是私有的，您是否有适当的访问权限

文件内容问题

• 某些文件类型可能不会返回内容（二进制文件、大文件）
• 检查文件路径是否正确
• 验证分支是否存在

依赖项

• fastmcp：MCP服务器框架
• requests：API调用的HTTP客户端
• pydantic：数据验证
• python-dotenv：环境变量管理

许可证

这个项目是开源的，可以在MIT许可证下使用。