A2atlassian

🏢 a2atlassian

Agent-to-Atlassian

让 AI Agent 使用 Jira 和 Confluence。凭据只需保存一次，即可随时随地使用。

Jira + Confluence · 默认只读 · 预配置连接 · 紧凑的 TSV 输出

快速开始 · MCP 工具 · 安全性 · 对比 · 配置

---

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 桥接程序。它们会向 Agent 上下文中塞入 72 个工具，而且存在一些已知问题，可能导致操作悄无声息地失败。a2atlassian 解决了所有这些问题：

• 无需 Docker — 运行 pip install a2atlassian 即可完成
• 预配置连接 — 使用 --register 在 .mcp.json 中定义项目，Agent 即可立即使用
• 默认只读 — 每个连接可单独选择是否启用写入权限
• 连接范围控制 — --scope 限制 Agent 可见的项目
• 紧凑输出 — 列表采用 TSV 格式（减少 30-60% 的令牌），单个实体采用 JSON 格式
• 动态加载工具 — 支持延迟加载工具的 MCP 客户端（例如 Claude Code）会按需加载工具，让上下文保持精简
• 增强错误信息 — 错误的字段名会获得建议，JQL 拼写错误会得到更正，已知问题会自动修复
• 密钥保留在环境中 — 配置中使用 ${ATLASSIAN_TOKEN}，仅在运行时展开

**当前支持范围：**完整支持 Jira（问题、评论、迭代、看板、工时记录、链接、版本、字段、关注者、项目）；Confluence 核心功能（页面 CRUD、搜索、仅修改元数据的写入操作）。

快速开始

# 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 [email protected] '${ATLASSIAN_TOKEN}'

Claude Code（最简配置 — 由 Agent 按需调用 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",
        "[email protected]", "${ATLASSIAN_TOKEN}"
      ],
      "env": {
        "ATLASSIAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

多个项目：

{
  "args": [
    "--from", "a2atlassian", "a2atlassian-mcp",
    "--register", "myproject", "https://mysite.atlassian.net", "[email protected]", "${TOKEN_A}",
    "--register", "personal", "https://personal.atlassian.net", "[email protected]", "${TOKEN_B}"
  ]
}

限定范围的连接（限制 Agent 可访问的已保存项目）：

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

--register 会创建临时内存连接（仅在进程运行期间有效，不会写入文件）。--scope 会筛选可见的已保存连接。两者都能限制影响范围。

作为 CLI 使用

# Save a connection (validates by calling /myself)
a2atlassian login -c myproject \
  --url https://mysite.atlassian.net \
  --email [email protected] \
  --token "$ATLASSIAN_TOKEN"

# Same, pulling the token from 1Password via `op`
a2atlassian login -c myproject \
  --url https://mysite.atlassian.net \
  --email [email protected] \
  --token "op://Personal/Atlassian/token"

# Enable writes
a2atlassian login -c myproject \
  --url https://mysite.atlassian.net \
  --email [email protected] \
  --token "$ATLASSIAN_TOKEN" \
  --no-read-only

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

令牌支持三种形式：字面值、${ENV_VAR} 引用，或 op://vault/item/field（运行时通过 1Password CLI 解析）。

MCP 工具

连接管理

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

Jira — 读取

工具	描述
jira_get_issue	按键获取问题 — 包含完整字段、状态和经办人
jira_search	使用 JQL 搜索并分页 — 默认输出精简 TSV
jira_search_count	仅统计 JQL 结果数量 — 快速预检查“结果会不会太多？”
jira_search_fields	按名称查找自定义字段 ID
jira_get_field_options	列出单选/多选字段的可选值
jira_get_comments	获取问题的所有评论
jira_get_worklogs	获取问题的所有工时记录
jira_get_transitions	查找可用的状态转换
jira_get_link_types	列出可用的问题链接类型
jira_get_watchers	列出问题的关注者
jira_get_projects	列出此连接可访问的项目
jira_get_project_metadata	获取创建元数据（问题类型、必填字段）
jira_get_user_profile	将电子邮件/accountId 解析为完整用户资料
jira_get_boards	列出项目中的敏捷看板
jira_get_board_issues	看板上的问题（分页）
jira_get_sprints	列出看板上的冲刺
jira_get_sprint_issues	冲刺中的问题（分页）

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

工具	描述
jira_create_issue	创建新问题
jira_update_issue	更新现有问题的字段
jira_delete_issue	删除问题
jira_transition_issue	将问题移至新状态
jira_add_comment	添加评论（wiki 标记，API v2）
jira_edit_comment	更新现有评论
jira_add_worklog	记录问题工时
jira_create_issue_link	链接两个问题
jira_remove_issue_link	移除问题链接
jira_set_watchers	替换问题的关注者列表
jira_create_sprint	在看板上创建冲刺
jira_update_sprint	更新冲刺状态/日期
jira_add_issues_to_sprint	将问题移入冲刺
jira_create_version	创建项目版本

Confluence — 读取

工具	描述
confluence_get_page	按 ID 获取页面（正文存储、版本、空间）
confluence_get_page_children	列出页面的直接子页面（分页）
confluence_search	CQL 搜索；每条匹配结果仅含最少字段

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

工具	描述
confluence_upsert_pages	批量创建或更新；省略正文时保留原内容，并返回每页状态及部分失败结果
confluence_set_page_properties	仅写入元数据（page_width、emoji、labels）— 无法修改正文或标题

输出格式

所有工具都接受 format 参数：

格式	默认用于	描述
toon	列表（搜索、评论）	带标题行的 TSV — 结构只需定义一次，数据可重复排列。比 JSON 少用 30-60% 的 token
json	单个实体（get_issue）	带元数据封装的标准 JSON

列表响应使用精简的 TSV 风格格式（标题行 + 制表符分隔的值），灵感来自 TOON。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 会告诉 Agent 应该怎么做：

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

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

自动处理的特殊情况：

• 经办人必须使用显示名称（不能使用 712020: 账户 ID）— 自动检测并提供提示
• Parent 字段必须是纯字符串 — {"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.

写入权限由人工操作员控制，而非 Agent。

凭据存储

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

• 文件权限： 0600（仅所有者可读写）
• ${ATLASSIAN_TOKEN} 语法 — 环境变量引用会按原样存储，并在运行时展开
• 输出中不含机密信息 — list_connections 会显示项目名称、URL 和模式，绝不显示令牌
• 临时模式 — --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
上下文中的工具	约 35 个（按需加载）	约 72 个	约 72 个
连接管理	TOML + --register + --scope	按会话使用 OAuth	.env 文件
多项目	支持（按范围限制）	不支持	每个设置使用一个 .env
默认只读	支持（按连接设置）	不支持	不支持
输出格式	TSV + JSON	JSON	JSON
错误信息增强	字段建议、特殊情况修复	通用错误	通用错误
特殊情况处理	自动修复（受指派人、父项）	文档说明的变通方法	文档说明的变通方法
速率限制	内置重试	不支持	不支持
命令行	支持	不支持	不支持
许可证	Apache 2.0	专有	MIT

路线图

已交付： 完整覆盖 Jira（v0.3.0）· Confluence 核心功能 + 支持完整 CommonMark 和 GFM 保真度的 markdown-to-storage（v0.4.0、v0.5.2）· 1Password op:// 令牌引用（v0.5.1）· 仅元数据的 Confluence 写入 + 省略正文时保留原正文的语义（v0.5.2）。

下一步： confluence_delete_page、Confluence 评论和附件、Confluence 集成测试路径。待办事项见 TODO.md。

按环境设置

本地（macOS / Linux）

# Recommended
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

# CLI
a2atlassian login -p myproject --url https://mysite.atlassian.net --email [email protected] --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 [email protected] "${CI_ATLASSIAN_TOKEN}"

开发

make bootstrap   # Install deps + pnpm + git hooks
make check       # Lint + test + coverage-diff + security (full gate)
make test        # Tests with coverage
make lint        # agent-harness + jscpd + actionlint (never modifies files)
make fix         # Auto-fix + lint
make similar     # Advisory: report similarly-named functions/classes

代码检查工具：ruff + ty（通过 agent-harness）、yamllint、jscpd（通过 pnpm 检测复制粘贴）、actionlint（GitHub Actions 工作流）。每次提交时，Pre-commit 钩子都会运行 agent-harness fix 和代码检查。通过 brew install pnpm actionlint 安装 pnpm 和 actionlint。

许可证

Apache 2.0

---

_{🏢 自 2025 年起，为 Agent 提供优先的 Atlassian 访问能力。}

_{由 Denis Tomilin 构建}