a2atlassian

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?

Существующие MCP-серверы Atlassian (Rovo, sooperset) требуют Docker, файлы .env и мосты mcp-remote. Они загружают 72 инструмента в контекст агента и имеют известные особенности, которые приводят к скрытым ошибкам. a2atlassian решает все эти проблемы:

• Без Docker — pip install a2atlassian и готово

• Предварительно настроенные подключения — определите проекты в .mcp.json с помощью --register, и агент сразу начнет работать

• По умолчанию только для чтения — доступ на запись включается отдельно для каждого подключения

• Область действия подключений — --scope ограничивает проекты, которые видит агент

• Компактный вывод — TSV для списков (на 30-60% меньше токенов), 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

Управление подключениями

Jira — Чтение

Jira — Запись (требуется подключение с правами чтения-записи)

Форматы вывода

Все инструменты принимают параметр format:

Ответы со списками используют компактный формат в стиле TSV (строка заголовка + значения, разделенные табуляцией), вдохновленный TOON. Это тот же подход, что использует a2db — имена столбцов появляются один раз, затем только значения. Для результата поиска из 50 задач это обычно экономит 40-60% токенов по сравнению с JSON.

Пример 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

Особенности, обрабатываемые автоматически:

• Исполнитель требует отображаемое имя (а не ID аккаунта 712020:) — автоматически определяется с подсказкой

• Поле родителя должно быть простой строкой — {"key": "PROJ-14"} молча нормализуется в "PROJ-14"

• Преобразование типа задачи не поддерживается через API — предоставляются четкие инструкции по интерфейсу Jira

Безопасность

По умолчанию только для чтения

Каждое подключение начинается в режиме «только чтение». Инструменты записи проверяют флаг подключения перед выполнением:

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

Человек-оператор контролирует доступ на запись, а не агент.

Хранение учетных данных

Подключения, сохраненные через login, попадают в ~/.config/a2atlassian/connections/ как файлы TOML:

• Права доступа к файлам: 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с перед выводом ошибки.

Сравнение

Дорожная карта

Фаза 1 (текущая): Ядро Jira — получение/поиск задач, комментарии (CRUD), переходы. Вторичный критический путь.

Фаза 2: Полная поверхность Jira — спринты, доски, связи, проекты, поля, журналы работ, вложения, наблюдатели.

Фаза 3: 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