setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setup — Prerequisites & MCP Configuration

安装设置 — 必备组件与MCP配置

Install CLI tools, authenticate to GitHub/GitLab, and configure the

mcp-atlassian

Jira integration for OpenCode.

安装CLI工具、完成GitHub/GitLab身份验证，并为OpenCode配置

mcp-atlassian

Jira集成。

Prerequisites

前置要求

Linux with
```
apt
```
package manager
```
bash
```
and
```
curl
```
available
Internet access (for apt packages and uv installer)

配备
```
apt
```
包管理器的Linux系统
可使用
```
bash
```
和
```
curl
```
可访问互联网（用于下载apt包和uv安装程序）

Trigger

触发条件

User says: "setup", "install prerequisites", "configure jira", or similar.

Important — interactive skill only. This skill requires user interaction (auth prompts, Jira credentials). It must not be called as a sub-step from autonomous skill pipelines (fast-meeting, issue-review, etc.) — doing so will stall the pipeline waiting for input that will never arrive.

用户说出："setup"、"install prerequisites"、"configure jira"或类似内容。

重要提示 — 仅支持交互式skill：本skill需要用户交互（身份验证提示、Jira凭证输入）。禁止在自主skill流水线（fast-meeting、issue-review等）中作为子步骤调用，否则流水线会因永远等待输入而停滞。

Workflow

工作流程

Phase 1 — Install CLI tools

阶段1 — 安装CLI工具

Run the bundled script to install missing tools (idempotent — skips already-installed ones):

bash

bash "$(dirname "$0")/reference/setup.sh"

The script installs (via

apt

if not already present):

```
gh
```
— GitHub CLI
```
glab
```
— GitLab CLI
```
jq
```
— JSON processor

uvx

— via the official

uv

installer (

curl -LsSf https://astral.sh/uv/install.sh | sh

)

After running, inform the user of what was installed vs. already present.

运行配套脚本安装缺失的工具（幂等设计 — 跳过已安装的工具）：

bash

bash "$(dirname "$0")/reference/setup.sh"

脚本会通过

apt

安装以下未预装的工具：

```
gh
```
— GitHub CLI
```
glab
```
— GitLab CLI
```
jq
```
— JSON处理器

uvx

— 通过官方

uv

安装程序安装（

curl -LsSf https://astral.sh/uv/install.sh | sh

）

运行完成后，告知用户哪些是新安装的、哪些是已存在的。

Phase 2 — CLI Authentication

阶段2 — CLI身份验证

Check and authenticate each CLI:

bash

gh auth status 2>&1

Show the full output to the user (current logged-in account, token scopes, etc.)
If not authenticated → tell the user: "Run
```
gh auth login
```
and follow the prompts."
Do NOT run
```
gh auth login
```
automatically (requires interactive input).

bash

glab auth status 2>&1

Show the full output to the user (GitLab instance, current user, token validity, etc.)
If not authenticated → tell the user: "Run
```
glab auth login
```
and follow the prompts."
Do NOT run
```
glab auth login
```
automatically.

检查每个CLI的身份验证状态并完成验证：

bash

gh auth status 2>&1

向用户展示完整输出（当前登录账号、token权限范围等）
若未完成身份验证 → 告知用户："运行
```
gh auth login
```
并按照提示操作。"
不要自动运行
```
gh auth login
```
（需要交互式输入）。

bash

glab auth status 2>&1

向用户展示完整输出（GitLab实例、当前用户、token有效性等）
若未完成身份验证 → 告知用户："运行
```
glab auth login
```
并按照提示操作。"
不要自动运行
```
glab auth login
```
。

Phase 3 — Configure mcp-atlassian for Jira

阶段3 — 为Jira配置mcp-atlassian

Step 3.1 — Check if uvx is available:

bash

uvx --version 2>&1 || ~/.local/bin/uvx --version 2>&1

If not found, remind the user to restart their shell or source

~/.bashrc

~/.profile

after the Phase 1 script ran.

Step 3.2 — Read existing OpenCode config:

Use the Read tool to read

~/.config/opencode/opencode.json

If the file does not exist, treat it as
```
{}
```
.
If
```
mcp.mcp-atlassian
```
is already present → confirm to the user and skip the rest of Phase 3.

Step 3.3 — Gather credentials (if not already configured):

Ask the user these two questions in a single message:

Jira URL — default
```
https://jira.dedalus.com/
```
(Server/Data Center). Press Enter to accept.
Jira Personal Access Token (PAT) — steps to generate one:
- Log in to your Jira instance
- Go to Profile → Personal Access Tokens
- Click Create token, give it a name, set an expiry
- Copy the token and paste it here

For Jira Cloud users: use
JIRA_USERNAME
(your email) +
JIRA_API_TOKEN
(from https://id.atlassian.com/manage-profile/security/api-tokens) instead of a PAT.

Step 3.4 — Write the config:

Merge the

mcp-atlassian

block into

~/.config/opencode/opencode.json

, preserving any existing content. Use the Write tool to write the final JSON.

For Server/Data Center (default):

json

{
  "mcp": {
    "mcp-atlassian": {
      "type": "local",
      "command": ["uvx", "mcp-atlassian"],
      "environment": {
        "JIRA_URL": "<jira-url>",
        "JIRA_PERSONAL_TOKEN": "<pat>"
      },
      "enabled": true
    }
  }
}

For Cloud (if user specifies):

json

{
  "mcp": {
    "mcp-atlassian": {
      "type": "local",
      "command": ["uvx", "mcp-atlassian"],
      "environment": {
        "JIRA_URL": "<jira-url>",
        "JIRA_USERNAME": "<email>",
        "JIRA_API_TOKEN": "<api-token>"
      },
      "enabled": true
    }
  }
}

Step 3.5 — Secure the config file:

bash

chmod 600 ~/.config/opencode/opencode.json

步骤3.1 — 检查uvx是否可用：

bash

uvx --version 2>&1 || ~/.local/bin/uvx --version 2>&1

如果找不到uvx，提醒用户在阶段1的脚本运行完成后重启shell，或者执行source命令加载

~/.bashrc

~/.profile

。

步骤3.2 — 读取现有OpenCode配置：

使用读取工具读取

~/.config/opencode/opencode.json

。

如果文件不存在，视为空对象
```
{}
```
。
如果
```
mcp.mcp-atlassian
```
已存在 → 向用户确认并跳过阶段3的剩余步骤。

步骤3.3 — 收集凭证（如果尚未配置）：

在同一条消息中向用户询问以下两个问题：

Jira URL — 默认值为
```
https://jira.dedalus.com/
```
（服务器/数据中心版本），按回车键即可使用默认值。
Jira个人访问令牌（PAT） — 生成步骤：
- 登录你的Jira实例
- 进入 个人资料 → 个人访问令牌
- 点击 创建令牌，命名令牌、设置过期时间
- 复制令牌并粘贴到此处

对于Jira Cloud用户：请使用
JIRA_USERNAME
（你的邮箱）+
JIRA_API_TOKEN
（可从https://id.atlassian.com/manage-profile/security/api-tokens 获取）替代PAT。

步骤3.4 — 写入配置：

将

mcp-atlassian

配置块合并到

~/.config/opencode/opencode.json

中，保留所有现有内容。使用写入工具写入最终的JSON。

服务器/数据中心版本（默认）：

json

{
  "mcp": {
    "mcp-atlassian": {
      "type": "local",
      "command": ["uvx", "mcp-atlassian"],
      "environment": {
        "JIRA_URL": "<jira-url>",
        "JIRA_PERSONAL_TOKEN": "<pat>"
      },
      "enabled": true
    }
  }
}

Cloud版本（用户指定时使用）：

json

{
  "mcp": {
    "mcp-atlassian": {
      "type": "local",
      "command": ["uvx", "mcp-atlassian"],
      "environment": {
        "JIRA_URL": "<jira-url>",
        "JIRA_USERNAME": "<email>",
        "JIRA_API_TOKEN": "<api-token>"
      },
      "enabled": true
    }
  }
}

步骤3.5 — 配置文件权限加固：

bash

chmod 600 ~/.config/opencode/opencode.json

Phase 4 — Summary

阶段4 — 配置总结

Print a clear summary table:

Component	Status
gh	installed / already ok
glab	installed / already ok
jq	installed / already ok
uvx	installed / already ok
gh auth	authenticated / action needed
glab auth	authenticated / action needed
mcp-atlassian	configured / already ok / skipped

End with: "Restart OpenCode to load the new MCP configuration."

打印清晰的总结表格：

组件	状态
gh	已安装 / 状态正常
glab	已安装 / 状态正常
jq	已安装 / 状态正常
uvx	已安装 / 状态正常
gh auth	已验证 / 需要操作
glab auth	已验证 / 需要操作
mcp-atlassian	已配置 / 状态正常 / 已跳过

结束提示："重启OpenCode以加载新的MCP配置。"