Agent: "What's the status of PROJ-42? Add a comment with the progress update."
  ↓
a2atlassian → get issue, add comment, transition to In Progress
  ↓
Agent: "Done — PROJ-42 updated and moved to In Progress."

为什么选择 a2atlassian？

现有的 Atlassian MCP 服务器（Rovo, sooperset）需要 Docker、.env 文件和 mcp-remote 网桥。它们会将 72 个工具一股脑塞进智能体上下文中，并且存在已知缺陷，导致静默失败。a2atlassian 解决了所有这些问题：

无需 Docker — pip install a2atlassian 即可完成
预配置连接 — 通过 --register 在 .mcp.json 中定义项目，智能体即可立即工作
默认只读 — 写入权限需针对每个连接单独开启
连接作用域 — --scope 限制智能体可见的项目范围
紧凑输出 — 列表使用 TSV（减少 30-60% 的 token），单个实体使用 JSON
动态工具加载 — 支持延迟加载工具的 MCP 客户端（例如 Claude Code）按需加载工具，保持上下文精简
错误增强 — 错误的字段名会获得建议，JQL 拼写错误会获得修正，缺陷会自动修复
密钥保留在环境变量中 — 配置中的 ${ATLASSIAN_TOKEN} 仅在运行时展开

快速开始

# Recommended — installs globally as a CLI tool
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

作为 MCP 服务器（推荐）

Claude Code（使用预配置连接）：

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp \
  --register myproject https://mysite.atlassian.net user@company.com '${ATLASSIAN_TOKEN}'

Claude Code（最小化配置 — 智能体按需调用 login）：

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp

Claude Desktop / Cursor / 任何 MCP 客户端 (.mcp.json)：

{
  "mcpServers": {
    "a2atlassian": {
      "command": "uvx",
      "args": [
        "--from", "a2atlassian", "a2atlassian-mcp",
        "--register", "myproject", "https://mysite.atlassian.net",
        "user@company.com", "${ATLASSIAN_TOKEN}"
      ],
      "env": {
        "ATLASSIAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

多个项目：

{
  "args": [
    "--from", "a2atlassian", "a2atlassian-mcp",
    "--register", "myproject", "https://mysite.atlassian.net", "user@a.com", "${TOKEN_A}",
    "--register", "personal", "https://personal.atlassian.net", "user@b.com", "${TOKEN_B}"
  ]
}

作用域连接（限制智能体仅访问特定的已保存项目）：

{
  "args": ["--from", "a2atlassian", "a2atlassian-mcp", "--scope", "myproject"]
}

--register 创建临时的内存连接（进程生命周期，不写入文件）。--scope 过滤可见的已保存连接。两者都限制了影响范围。

作为 CLI

# Save a connection (validates by calling /myself)
a2atlassian login -p myproject \
  --url https://mysite.atlassian.net \
  --email user@company.com \
  --token "$ATLASSIAN_TOKEN"

# Enable writes
a2atlassian login -p myproject \
  --url https://mysite.atlassian.net \
  --email user@company.com \
  --token "$ATLASSIAN_TOKEN" \
  --no-read-only

# List / remove connections
a2atlassian connections
a2atlassian logout -p myproject

MCP 工具

连接管理

工具	描述
`login`	保存连接 — 通过首先调用 /myself 进行验证
`logout`	移除已保存的连接
`list_connections`	列出连接（不暴露密钥）

Jira — 读取

工具	描述
`jira_get_issue`	按键获取问题 — 包含完整字段、状态、经办人
`jira_search`	使用 JQL 分页搜索 — 默认输出紧凑的 TSV
`jira_get_comments`	获取问题的所有评论
`jira_get_transitions`	发现可用的状态转换

Jira — 写入（需要读写连接）

工具	描述
`jira_add_comment`	添加评论（wiki 标记，API v2）
`jira_edit_comment`	更新现有评论
`jira_transition_issue`	将问题移动到新状态

输出格式

所有工具都接受 format 参数：

格式	默认用于	描述
`toon`	列表（搜索、评论）	带标题的 TSV — 定义一次，多次数据。比 JSON 少 30-60% 的 token
`json`	单个实体 (get_issue)	带有元数据包装的标准 JSON

列表响应使用受 TOON 启发的紧凑 TSV 风格格式（标题行 + 制表符分隔的值）。这是 a2db 使用的相同方法 — 列名只出现一次，后面仅跟值。对于 50 个问题的搜索结果，这通常比 JSON 节省 40-60% 的 token。

TSV 示例（搜索结果）：

# search (23 results, 50ms, truncated: False)
key	summary	assignee	status
PROJ-142	Fix auth timeout	Alice Smith	In Progress
PROJ-141	Add search filters	Bob Jones	To Do

JSON 示例（单个问题）：

{
  "data": {"key": "PROJ-142", "fields": {"summary": "Fix auth timeout", ...}},
  "count": 1,
  "truncated": false,
  "time_ms": 85
}

错误增强

当出现故障时，a2atlassian 会告诉智能体该怎么做：

Field 'asignee' does not exist
Did you mean: assignee?

Connection 'myproject' is read-only.
Run: a2atlassian login -p myproject --read-only false

自动处理的缺陷：

经办人需要显示名称（而非 712020: 账户 ID） — 通过提示自动检测
父级字段必须是纯字符串 — {"key": "PROJ-14"} 被静默规范化为 "PROJ-14"
API 不支持问题类型转换 — 提供清晰的 Jira UI 操作说明

安全性

默认只读

每个连接默认以只读方式启动。写入工具在执行前会检查连接标志：

Connection 'myproject' is read-only.
Re-run 'a2atlassian login -p myproject --read-only false' to enable writes.

人类操作员控制写入权限，而非智能体。

凭据存储

通过 login 保存的连接以 TOML 文件形式存储在 ~/.config/a2atlassian/connections/ 中：

文件权限： 0600（仅所有者可读写）
${ATLASSIAN_TOKEN} 语法 — 环境变量引用按字面存储，在运行时展开
输出中无密钥 — list_connections 显示项目名称、URL 和模式 — 绝不显示 token
临时模式 — --register 将凭据仅保留在内存中，绝不写入磁盘

连接作用域

使用 --scope 限制特定 MCP 实例可以访问的已保存连接：

# Project config — only myproject visible, even if other connections are saved
uvx --from a2atlassian a2atlassian-mcp --scope myproject

项目级 MCP 配置 (.claude/mcp.json) 会覆盖全局配置 — 每个仓库仅能看到其自己的连接。

速率限制

内置针对 Atlassian 速率限制 (429) 和瞬态服务器错误 (500) 的指数退避重试机制。在抛出错误前，会在 1 秒和 3 秒间隔进行两次重试。

对比

特性	a2atlassian	Rovo (官方)	sooperset/mcp-atlassian
设置	`pip install`	OAuth + Docker	Docker + .env + mcp-remote
上下文中的工具	10 (第一阶段)	~72	~72
连接管理	TOML + `--register` + `--scope`	会话级 OAuth	.env 文件
多项目	是 (作用域)	否	每个设置一个 .env
默认只读	是 (每个连接)	否	否
输出格式	TSV + JSON	JSON	JSON
错误增强	字段建议，缺陷修复	通用错误	通用错误
缺陷处理	自动修复 (经办人, 父级)	文档化变通方案	文档化变通方案
速率限制	内置重试	否	否
CLI	是	否	否
许可证	Apache 2.0	专有	MIT

路线图

第一阶段（当前）： Jira 核心 — 获取/搜索问题、评论 (CRUD)、状态转换。这是次要的关键路径。

第二阶段： Jira 全面覆盖 — 冲刺、看板、链接、项目、字段、工作日志、附件、关注者。

第三阶段： Confluence — 页面、评论、附件、标签、搜索。

设置

本地 (macOS / Linux)

# Recommended
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

# CLI
a2atlassian login -p myproject --url https://mysite.atlassian.net --email me@co.com --token "$TOKEN"

# Or add as MCP server (see Quick Start)

CI / 自动化

uv tool install a2atlassian

# Pre-configured — no login needed
uvx --from a2atlassian a2atlassian-mcp --register ci https://mysite.atlassian.net ci-user@co.com "${CI_ATLASSIAN_TOKEN}"

开发

make bootstrap   # Install deps + hooks
make check       # Lint + test + security (full gate)
make test        # Tests with coverage
make lint        # Lint only (never modifies files)
make fix         # Auto-fix + lint

许可证

Apache 2.0

a2atlassian