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."

Warum a2atlassian?

Bestehende Atlassian-MCP-Server (Rovo, sooperset) erfordern Docker, .env-Dateien und mcp-remote-Brücken. Sie laden 72 Tools in den Agenten-Kontext und haben bekannte Eigenheiten, die unbemerkt zu Fehlern führen. a2atlassian löst all das:

Kein Docker — pip install a2atlassian und fertig
Vorkonfigurierte Verbindungen — Projekte in .mcp.json mit --register definieren, der Agent arbeitet sofort
Standardmäßig schreibgeschützt — Schreibzugriff ist pro Verbindung optional
Verbindungs-Scoping — --scope begrenzt, welche Projekte ein Agent sehen kann
Kompakte Ausgabe — TSV für Listen (30-60% weniger Token), JSON für einzelne Entitäten
Dynamisches Laden von Tools — MCP-Clients, die verzögerte Tools unterstützen (z. B. Claude Code), laden Tools bei Bedarf, was den Kontext schlank hält
Fehleranreicherung — falsche Feldnamen erhalten Vorschläge, JQL-Tippfehler werden korrigiert, Eigenheiten werden automatisch behoben
Geheimnisse bleiben in der Umgebung — ${ATLASSIAN_TOKEN} in Konfigurationen wird erst zur Laufzeit erweitert

Schnellstart

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

# Or with pip
pip install a2atlassian

Als MCP-Server (empfohlen)

Claude Code (mit vorkonfigurierter Verbindung):

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

Claude Code (minimal — Agent ruft login bei Bedarf auf):

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

Claude Desktop / Cursor / beliebiger MCP-Client (.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"
      }
    }
  }
}

Mehrere Projekte:

{
  "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}"
  ]
}

Gescopte Verbindungen (Agent auf bestimmte gespeicherte Projekte beschränken):

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

--register erstellt flüchtige In-Memory-Verbindungen (Prozesslebensdauer, keine Dateien geschrieben). --scope filtert, welche gespeicherten Verbindungen sichtbar sind. Beides begrenzt den Wirkungsradius.

Als 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-Tools

Verbindungsverwaltung

Tool	Beschreibung
`login`	Verbindung speichern — validiert durch vorherigen Aufruf von /myself
`logout`	Gespeicherte Verbindung entfernen
`list_connections`	Verbindungen auflisten (keine Geheimnisse offengelegt)

Jira — Lesen

Tool	Beschreibung
`jira_get_issue`	Vorgang nach Schlüssel abrufen — vollständige Felder, Status, Bearbeiter
`jira_search`	Suche nach JQL mit Paginierung — standardmäßig kompakte TSV-Ausgabe
`jira_get_comments`	Alle Kommentare zu einem Vorgang abrufen
`jira_get_transitions`	Verfügbare Statusübergänge entdecken

Jira — Schreiben (erfordert Lese-/Schreibverbindung)

Tool	Beschreibung
`jira_add_comment`	Kommentar hinzufügen (Wiki-Markup, API v2)
`jira_edit_comment`	Bestehenden Kommentar aktualisieren
`jira_transition_issue`	Vorgang in neuen Status verschieben

Ausgabeformate

Alle Tools akzeptieren einen format-Parameter:

Format	Standard für	Beschreibung
`toon`	Listen (Suche, Kommentare)	TSV mit Kopfzeile — Struktur einmal, Daten mehrfach. 30-60% weniger Token als JSON
`json`	Einzelne Entitäten (get_issue)	Standard-JSON mit Metadaten-Umschlag

Listenantworten verwenden ein kompaktes TSV-ähnliches Format (Kopfzeile + tabulatorgetrennte Werte), inspiriert von TOON. Dies ist der gleiche Ansatz, den a2db verwendet — Spaltennamen erscheinen einmal, danach nur noch Werte. Bei einem Suchergebnis mit 50 Vorgängen spart dies im Vergleich zu JSON typischerweise 40-60% der Token.

TSV-Beispiel (Suchergebnisse):

# 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-Beispiel (einzelner Vorgang):

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

Fehleranreicherung

Wenn etwas fehlschlägt, sagt a2atlassian dem Agenten, was zu tun ist:

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

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

Automatisch behandelte Eigenheiten:

Bearbeiter erfordert Anzeigenamen (keine 712020: Account-IDs) — automatisch mit Hinweis erkannt
Parent-Feld muss ein einfacher String sein — {"key": "PROJ-14"} wird stillschweigend zu "PROJ-14" normalisiert
Vorgangstyp-Konvertierung über API nicht unterstützt — klare Jira-UI-Anweisungen bereitgestellt

Sicherheit

Standardmäßig schreibgeschützt

Jede Verbindung startet schreibgeschützt. Schreib-Tools prüfen das Verbindungs-Flag vor der Ausführung:

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

Der menschliche Bediener kontrolliert den Schreibzugriff — nicht der Agent.

Speicherung von Anmeldedaten

Verbindungen, die über login gespeichert werden, landen als TOML-Dateien in ~/.config/a2atlassian/connections/:

Dateiberechtigungen: 0600 (nur Besitzer kann lesen/schreiben)
${ATLASSIAN_TOKEN}-Syntax — Umgebungsvariablen-Referenzen werden wörtlich gespeichert und erst zur Laufzeit erweitert
Keine Geheimnisse in der Ausgabe — list_connections zeigt Projektname, URL und Modus — niemals Token
Flüchtiger Modus — --register hält Anmeldedaten nur im Arbeitsspeicher, sie werden nie auf die Festplatte geschrieben

Verbindungs-Scoping

Verwenden Sie --scope, um zu begrenzen, auf welche gespeicherten Verbindungen eine bestimmte MCP-Instanz zugreifen kann:

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

Projekt-spezifische MCP-Konfigurationen (.claude/mcp.json) überschreiben globale Konfigurationen — jedes Repository sieht nur seine eigenen Verbindungen.

Ratenbegrenzung

Eingebautes Retry mit exponentiellem Backoff für Atlassians Ratenbegrenzungen (429) und vorübergehende Serverfehler (500). Zwei Wiederholungsversuche in Abständen von 1s und 3s, bevor der Fehler gemeldet wird.

Vergleich

Funktion	a2atlassian	Rovo (offiziell)	sooperset/mcp-atlassian
Einrichtung	`pip install`	OAuth + Docker	Docker + .env + mcp-remote
Tools im Kontext	10 (Phase 1)	~72	~72
Verbindungsverwaltung	TOML + `--register` + `--scope`	Sitzungsbasiertes OAuth	.env-Datei
Multi-Projekt	Ja (gescopt)	Nein	Eine .env pro Einrichtung
Standard schreibgeschützt	Ja (pro Verbindung)	Nein	Nein
Ausgabeformat	TSV + JSON	JSON	JSON
Fehleranreicherung	Feldvorschläge, Fehlerbehebungen	Generische Fehler	Generische Fehler
Umgang mit Eigenheiten	Auto-Fix (Bearbeiter, Parent)	Dokumentierte Workarounds	Dokumentierte Workarounds
Ratenbegrenzung	Eingebautes Retry	Nein	Nein
CLI	Ja	Nein	Nein
Lizenz	Apache 2.0	Proprietär	MIT

Roadmap

Phase 1 (aktuell): Jira-Kern — Vorgänge abrufen/suchen, Kommentare (CRUD), Übergänge. Der sekundäre kritische Pfad.

Phase 2: Vollständige Jira-Oberfläche — Sprints, Boards, Links, Projekte, Felder, Arbeitsprotokolle, Anhänge, Beobachter.

Phase 3: Confluence — Seiten, Kommentare, Anhänge, Labels, Suche.

Einrichtung nach Umgebung

Lokal (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 / Automatisierung

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}"

Entwicklung

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

Lizenz

Apache 2.0

a2atlassian