Stash MCP

MCP服务器损坏

  ](https://hub.docker.com/r/diomonogatari/stash-mcp) ](https://hub.docker.com/r/diomonogatari/stash-mcp) ](https://github.com/diomonogatari/stash-mcp/releases) 

Atlassian Bitbucket server（Stash）的模型上下文协议（MCP）服务器，作为Docker镜像发布在 。它让人工智能助手通过40个专门构建的工具访问您的存储库、拉取请求、代码审查、构建和搜索。

特性

40工具 涵盖全面的Bitbucket服务器工作流程：

工作流优化工具

这些工具将多个API调用减少为单个调用：

• get_pull_request_context --完成公关，包括评论、任务、差异、活动
• get_repository_overview --一次调用中包含分支、标签和打开的PR
• get_commit_context --提交带有更改和差异的细节

韧性

• 断路器 --防止Bitbucket不可用时发生级联故障
• 使用回退重试 --暂时错误的自动重试（429502503504）
• 故障弱化 -当API失败时返回缓存的数据
• 响应截断 --50KB限制可防止上下文溢出
• 缓存失效 --写入操作会自动刷新相关缓存

入门指南

先决条件

• 安装
• Bitbucket服务器（自托管）实例
• 具有存储库读/写权限的个人访问令牌

VS代码/副本——MCP配置

将以下内容添加到VS Code MCP配置文件中 （命令选项板→ MCP: Open user configuration):

{
  "servers": {
    "stash-bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_URL",
        "-e", "BITBUCKET_TOKEN",
        "diomonogatari/stash-mcp:latest"
      ],
      "env": {
        "BITBUCKET_URL": "https://your-stash-server.com/",
        "BITBUCKET_TOKEN": "your_personal_access_token"
      },
      "type": "stdio"
    }
  }
}

就是这样。VS Code将在首次使用时提取图像并自动启动服务器。

提示--固定到特定标签 而不是 latest （例如。 diomonogatari/stash-mcp:1.1.0) 以避免在发布新版本时运行过时的本地映像。 当本地镜像已经具有 latest 标签。 如果你必须使用 latest，用力拉 docker run --pull=always ... diomonogatari/stash-mcp:latest.

高级配置

传递其他环境变量以调整弹性和缓存行为：

{
  "servers": {
    "stash-bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_URL",
        "-e", "BITBUCKET_TOKEN",
        "-e", "BITBUCKET_RETRY_COUNT",
        "-e", "BITBUCKET_CIRCUIT_TIMEOUT",
        "-e", "BITBUCKET_CACHE_TTL_SECONDS",
        "-e", "BITBUCKET_READ_ONLY_MODE",
        "-e", "BITBUCKET_PROJECTS",
        "diomonogatari/stash-mcp:latest"
      ],
      "env": {
        "BITBUCKET_URL": "https://your-stash-server.com/",
        "BITBUCKET_TOKEN": "your_personal_access_token",
        "BITBUCKET_RETRY_COUNT": "5",
        "BITBUCKET_CIRCUIT_TIMEOUT": "60",
        "BITBUCKET_CACHE_TTL_SECONDS": "120",
        "BITBUCKET_READ_ONLY_MODE": "false",
        "BITBUCKET_PROJECTS": "PROJ,TEAM"
      },
      "type": "stdio"
    }
  }
}

配置参考

工具参考

有关所有40个工具的详细文档，请参阅 docs/TOOLSET.md.

常见工作流

代码审查

1. get_pull_request_context (with includeComments=true, includeDiff=true)
2. Review the diff and existing comments
3. add_pull_request_comment (for feedback)
4. create_pull_request_task (for required changes)
5. approve_pull_request (when satisfied)

Bug调查

1. search_commits (messageContains="JIRA-123")
2. get_commit_context (includeDiff=true)
3. search_code (to find current implementation)

存储库探索

1. get_repository_overview (quick overview)
2. list_files (browse structure)
3. get_file_content (read specific files)

输出优化

对于列表操作，请使用 minimalOutput=true 为了减小响应大小：

• list_repositories --仅返回存储库蛞蝓
• list_branches --仅返回分支名称
• list_pull_requests --返回精简的PR摘要

贡献

设置

1. 克隆存储库 带有子模块:

   git clone --recurse-submodules https://github.com/diomonogatari/stash-mcp.git

如果你已经克隆了，没有子模块：

   git submodule update --init --recursive

1. 安装 .NET 10.0 SDK

建筑

# Build the solution
dotnet build stash-mcp.slnx

# Run tests
dotnet test stash-mcp.slnx

本地运行

dotnet run --project src/StashMcpServer/StashMcpServer.csproj -- \
  --stash-url https://your-server.com/ --pat your_pat

双人冲刺(--)分开 dotnet run 从应用程序参数中提取参数。

CLI标志

构建Docker镜像

docker build -t diomonogatari/stash-mcp:dev .
docker run -i --rm \
  -e BITBUCKET_URL=https://your-stash-server.com/ \
  -e BITBUCKET_TOKEN=your_personal_access_token \
  diomonogatari/stash-mcp:dev

故障排除

Docker镜像未更新

Docker在以下情况下跳过pull latest 标记已在本地存在。 强制进行新的拉动：

docker pull diomonogatari/stash-mcp:latest

或固定到特定的版本标签（例如。 diomonogatari/stash-mcp:1.1.0).

连接被拒绝/超时

• 验证 BITBUCKET_URL 包括尾随斜线和协议

(https://your-server.com/)

• 确保Docker容器可以访问您的Bitbucket服务器（检查

公司VPN、代理或防火墙规则）

• 对于macOS/Windows上的Docker桌面，请使用 host.docker.internal 如果

Bitbucket在主机上运行

权限错误（401/403）

• 验证个人访问令牌是否具有 存储库读取 （以及

存储库写入 如果你需要写操作）权限

• 检查令牌是否未过期
• 集 BITBUCKET_READ_ONLY_MODE=true 如果只需要读取权限

服务器启动后无响应

• 提高日志级别以查看发生了什么：

--log-level Debug （CLI）或附加 --log-level Debug 在图像之后 姓名在 docker run 命令

• 检查一下 BITBUCKET_PROJECTS 变量（如果设置）包含

有效的项目密钥--无效的密钥会导致启动缓存失败 默默地

建筑

┌──────────────────────────────────────────────────────────┐
│                      MCP Server Layer                    │
│  ┌──────────────────────────────────────────────────┐    │
│  │ Domain Tool Classes (9 classes, 40 tools)        │    │
│  │  ProjectTools  RepositoryTools  PullRequestTools │    │
│  │  SearchTools   GitTools   HistoryTools           │    │
│  │  BuildTools    DashboardTools  IntegrationTools  │    │
│  └──────────┬───────────────────────────────────────┘    │
│             │ inherits ToolBase (shared helpers)         │
│  ┌──────────▼───────────────────────────────────────┐    │
│  │ Formatting  │ DiffFormatter  ResponseTruncation  │    │
│  │             │ MinimalOutputFormatter (50KB limit)│    │
│  └──────────┬───────────────────────────────────────┘    │
│             │                                            │
│  ┌──────────▼───────────────────────────────────────┐    │
│  │           ResilientApiService                    │    │
│  │  • Circuit Breaker (Polly)                       │    │
│  │  • Retry with Exponential Backoff                │    │
│  │  • Graceful Degradation (stale cache)            │    │
│  │  • Cache Invalidation on Writes                  │    │
│  └──────────┬───────────────────────────────────────┘    │
│             │                                            │
│  ┌──────────▼──────┐ ┌──────────────────────────────┐    │
│  │ Cache Layer      │ │ IMemoryCache (TTL=60s)      │    │
│  │ (Static)         │ │ ConcurrentDict (projects)   │    │
│  └──────────┬──────┘ └──────────────────────────────┘    │
│             │                                            │
│  Transport: stdio                                        │
└─────────────┼────────────────────────────────────────────┘
              │
              ▼
       Bitbucket Server API (via Bitbucket.Net submodule)

有关详细的体系结构文档，请参阅 docs/ARCHITECTURE.md.

安全

切勿将您的个人访问令牌提交给源代码管理。

• 使用环境变量（如上面的配置示例所示）
• 将PAT权限限制在所需的最小范围内
• 在可用的情况下使用安全的凭据存储

文档

• 建筑 --系统设计和文件夹结构
• 工具参考 --所有40个工具的详细文档
• 贡献 --开发设置和拉取请求指南
• 安全 --漏洞报告和凭证安全
• 更新日志 --版本历史和发行说明

星迹

许可证

看 许可证 了解详情。