内容
# Sberworks MCP
用于 Jira、Confluence 和 Bitbucket Server/Data Center 的本地标准输入输出 MCP 服务器。
## 前置条件
- Python 3.11 或更新版本。
- 推荐使用 `uv` 进行日常设置。
- `cryptography` 用于读取 `CLIENT_P12_PATH`；不需要外部 OpenSSL 二进制文件。
该服务器是跨平台的，支持 Windows、macOS 和 Linux。MCP 客户端可以从任意工作目录启动它，只需使用生成的配置代码段。
## 使用 uv 快速开始
PowerShell:
```powershell
cd path\to\sberworks-mcp
uv run sberworks-mcp init
uv run sberworks-mcp doctor
uv run sberworks-mcp config-snippet --client claude
```
bash/zsh:
```bash
cd /path/to/sberworks-mcp
uv run sberworks-mcp init
uv run sberworks-mcp doctor
uv run sberworks-mcp config-snippet --client claude
```
如果未安装 `uv`，请使用以下备用方法。
## 使用 venv 和 pip 备用
PowerShell:
```powershell
cd path\to\sberworks-mcp
python -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[dev]"
.\.venv\Scripts\sberworks-mcp init
.\.venv\Scripts\sberworks-mcp doctor
.\.venv\Scripts\sberworks-mcp config-snippet --client claude
```
bash/zsh:
```bash
cd /path/to/sberworks-mcp
python3 -m venv .venv
./.venv/bin/python -m pip install -e ".[dev]"
./.venv/bin/sberworks-mcp init
./.venv/bin/sberworks-mcp doctor
./.venv/bin/sberworks-mcp config-snippet --client claude
```
## 首次运行
运行设置助手：
```powershell
sberworks-mcp init
```
`init` 仅创建本地 `.env` 文件。它不会编辑 Claude、Codex、VS Code 或其他客户端配置文件。除非您传递 `--force`，否则不会覆盖现有的 `.env` 文件。
验证结果：
```powershell
sberworks-mcp doctor
```
生成客户端配置代码段：
```powershell
sberworks-mcp config-snippet --client claude
sberworks-mcp config-snippet --client codex
sberworks-mcp config-snippet --client vscode
```
代码段使用：
- 绝对 Python 可执行文件路径作为 `command`；
- `args = ["-m", "sberworks_mcp"]`；
- 绝对 `SBERWORKS_MCP_ENV_FILE` 路径。
这避免了常见的 MCP 问题，即桌面客户端从意外的当前工作目录或继承的环境启动服务器。
## 客户端配置
### Claude 桌面版
生成：
```powershell
sberworks-mcp config-snippet --client claude
```
将 JSON 粘贴到顶级配置对象下。
配置路径：
- Windows： `%APPDATA%\Claude\claude_desktop_config.json`
- macOS： `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux： Claude Desktop 可能没有官方 Linux 版本；请改用 Claude Code、Codex 或 VS Code 代码段。
编辑配置后重启 Claude Desktop。
### Codex
生成：
```powershell
sberworks-mcp config-snippet --client codex
```
将 TOML 块添加到您的 Codex 配置中，通常是 `~/.codex/config.toml`。
### VS Code
生成：
```powershell
sberworks-mcp config-snippet --client vscode
```
在 `.vscode/mcp.json` 或用户级 MCP 配置中使用输出。VS Code 使用顶级 `servers` 对象，而不是 `mcpServers`。
## Docker
构建本地镜像：
```powershell
docker build -t sberworks-mcp:local .
```
容器运行相同的标准输入输出 MCP 服务器。对于 MCP 客户端，请使用 `-i` 保持标准输入打开：
```powershell
docker run --rm -i `
--env-file .env `
-e SBERWORKS_MCP_ENV_FILE=/config/.env `
-v ${PWD}/.env:/config/.env:ro `
-v ${PWD}/certs:/certs:ro `
-v ${PWD}/attachments:/attachments:ro `
sberworks-mcp:local serve
```
使用 Docker Compose：
```powershell
docker compose build
docker compose run --rm -T sberworks-mcp doctor
docker compose run --rm -T sberworks-mcp
```
生成基于 Docker 的客户端代码段：
```powershell
sberworks-mcp config-snippet --client claude --runtime docker
sberworks-mcp config-snippet --client codex --runtime docker
sberworks-mcp config-snippet --client vscode --runtime docker
```
如果您在另一个标签下构建了镜像，请使用 `--image`：
```powershell
sberworks-mcp config-snippet --client claude --runtime docker --image custom/sberworks-mcp:test
```
生成的代码段使用 `command = docker` 并传递 `run --rm -i`、`--env-file`、`.env` 挂载在 `/config/.env` 处，以及 `/certs` 和 `/attachments` 的只读挂载。
在 Docker 中运行时，`.env` 内的路径必须是容器路径。例如：
```dotenv
REQUESTS_CA_BUNDLE=/certs/ca.pem
CLIENT_P12_PATH=/certs/client.p12
```
请勿发布本地运行时文件。`.env`、`certs/`、`.cert_cache/` 和 `attachments/` 已被故意排除在 git 和 Docker 构建上下文之外。
## 手动运行
对于正常的 MCP 客户端使用，客户端启动服务器。对于手动标准输入输出启动：
```powershell
sberworks-mcp
```
或：
```powershell
sberworks-mcp serve
```
`python -m sberworks_mcp` 也受支持。
## 环境
必需：
- `JIRA_BASE_URL`
- `CONFLUENCE_BASE_URL`
- `BITBUCKET_BASE_URL`
- `AUTH_USERNAME`
- `AUTH_PASSWORD`
Zephyr 方法使用 `JIRA_BASE_URL` 和相同的 Jira 身份验证。它们针对 `/rest/atm/latest` API 命名空间。
可选：
- `BITBUCKET_SERVER_BEARER_TOKEN`：优先用于 Bitbucket 身份验证。
- `REQUESTS_CA_BUNDLE`：企业 CA 捆绑路径。
- `CLIENT_P12_PATH` 和 `CLIENT_P12_PASSWORD`：P12 格式的客户端证书。
- `SBERWORKS_MCP_CERT_CACHE_DIR`：转换后的 PEM 证书文件的目录。默认为 `.cert_cache`，位于 `SBERWORKS_MCP_ENV_FILE` 旁边，因此桌面客户端可以从任意工作目录启动 MCP 服务器。
- `SBERWORKS_MCP_DOWNLOAD_DIR`：`bitbucket_download_file` 的默认目录。默认为 `sberworks-mcp-downloads` 下的系统临时目录。
- `SBERWORKS_MCP_ENABLE_WRITES`：默认为 `false`。
- `SBERWORKS_MCP_TIMEOUT_SECONDS`：默认为 `30`。
默认情况下，写入工具处于禁用状态。请在只读工具正常工作后显式启用写入工具：
```powershell
$env:SBERWORKS_MCP_ENABLE_WRITES = "true"
```
或在 `.env` 中设置：
```dotenv
SBERWORKS_MCP_ENABLE_WRITES=true
```
## 工具
Jira：
- `jira_search`
- `jira_get_issue`
- `jira_get_comments`
- `jira_get_remote_links`
- `jira_get_development_details`
- `jira_add_comment`
- `jira_create_issue`
- `jira_add_attachment`
- `jira_update_issue_fields`
- `jira_list_transitions`
- `jira_transition_issue`
Confluence：
- `confluence_search`
- `confluence_get_page`
- `confluence_get_children`
- `confluence_create_page`
- `confluence_update_page`
- `confluence_add_comment`
Bitbucket：
- `bitbucket_get_repo`
- `bitbucket_list_repositories`
- `bitbucket_create_repo`
- `bitbucket_list_pull_requests`
- `bitbucket_get_pull_request`
- `bitbucket_find_pull_requests_by_issue_key`
- `bitbucket_get_pr_diff`
- `bitbucket_get_file`
- `bitbucket_download_file`
- `bitbucket_put_file`
- `bitbucket_add_pr_comment`
- `bitbucket_create_pull_request`
Zephyr：
- `zephyr_get_cycle`
- `zephyr_get_cycle_case_keys`
- `zephyr_get_test_case`
- `zephyr_get_test_cases`
- `zephyr_get_test_case_details`
- `zephyr_export_cycle_cases`
- `zephyr_export_cycle_case_details`
- `zephyr_probe_cycle_endpoints`
## 资源
- `jira://issue/{key}`
- `confluence://page/{page_id}`
- `bitbucket://projects/{project}/repos/{repo}/files/{path}?at={ref}`
- `zephyr://cycle/{cycle_key}`
- `zephyr://testcase/{case_key}`
## 故障排除
- 运行 `sberworks-mcp doctor --env-file /absolute/path/to/.env`。
- 在 MCP 客户端配置和 `.env` 文件引用中使用绝对路径。
- 不要在服务器模式下将 MCP 协议日志写入标准输出；标准输出保留用于 JSON-RPC。
- 检查客户端日志，当服务器未出现时。
- Claude Desktop Windows 日志： `%APPDATA%\Claude\logs`
- Claude Desktop macOS 日志： `~/Library/Logs/Claude`
- 当客户端无法连接时，使用 MCP Inspector 进行测试。
- 如果设置了 `CLIENT_P12_PATH`，请确保文件路径对于桌面 MCP 客户端是绝对的。
## 测试
```powershell
python -m pytest
```
