atlassian-proxy

Lokaler stdio-MCP-Proxy, der vor Atlassians gehostetem Rovo-MCP-Server (https://mcp.atlassian.com/v1/mcp) sitzt und ihn für Claude Code zurechtstutzt.

Claude Code (stdio) -> index.js -> mcp-remote (subprocess, OAuth) -> https://mcp.atlassian.com/v1/mcp

Was er tut:

• Stellt nur die in ALLOWED_TOOLS in index.js aufgeführten Tools bereit (diejenigen, die jira-ops/jira-reviewer tatsächlich verwenden) – alles andere upstream wird vor tools/list verborgen.

• Injiziert automatisch cloudId, contentFormat, responseContentFormat in jeden Aufruf und entfernt diese Parameter aus dem Schema, das Claude sieht, sodass Claude nie davon erfahren muss.

• Entfernt rekursiv verrauschte Schlüssel (avatarUrls, self, iconUrl, _links, expand, browseUrl, ...) aus jedem Tool-Ergebnis, bevor es zurückgegeben wird.

Voraussetzungen

• Node.js (beliebige Version, die natives ESM / type: "module" unterstützt).

• npx muss im PATH verfügbar sein (wird verwendet, um mcp-remote zu starten).

Related MCP server: JIRA MCP Server

Installation

Prüfen Sie zuerst, ob Node.js bereits installiert ist – wenn ja und node_modules bereits in diesem Ordner vorhanden ist, ist npm install nicht erforderlich:

node -v

Falls das fehlschlägt (Node nicht gefunden), installieren Sie zuerst Node.js, dann:

cd C:\Users\Dz\oktanetest\atlassian-proxy
npm install

Dies installiert @modelcontextprotocol/sdk und mcp-remote aus package.json.

Eigenständig ausführen (manueller Smoke-Test)

node index.js

Es spricht MCP über stdio, daher blockiert die direkte Ausführung einfach und wartet auf einen Client auf stdin. Beim ersten Aufruf eines Jira-/Confluence-Tools startet es npx -y mcp-remote https://mcp.atlassian.com/v1/mcp als Kindprozess, der ein Browserfenster für die Atlassian-OAuth-Anmeldung öffnet. Nach der Autorisierung speichert mcp-remote das Token zwischen, sodass spätere Ausführungen keine erneute Authentifizierung benötigen. [atlassian-proxy] ready auf stderr bedeutet, dass die Verbindung zum Upstream hergestellt wurde und die gefilterte Tool-Liste bereitgestellt wird.

Bei Claude Code registrieren

Registrieren Sie diesen Proxy unter dem Namen atlassian-proxy, nicht atlassian – das verhindert eine Kollision mit dem echten gehosteten Atlassian-/Rovo-MCP-Server, falls dieser ebenfalls unter atlassian registriert ist.

Fügen Sie ihn als stdio-MCP-Server für das Projekt hinzu, z. B. in der Claude-Code-Konfiguration des Projekts (mcpServers-Block):

{
  "atlassian-proxy": {
    "type": "stdio",
    "command": "node",
    "args": ["<path-to-atlassian-proxy>\\index.js"],
    "env": {}
  }
}

Wenn der echte atlassian-MCP-Server ebenfalls registriert ist, deaktivieren Sie ihn (nicht entfernen), sodass nur die gefilterten Tools dieses Proxys aktiv sind: Führen Sie /mcp in Claude Code aus, wählen Sie den atlassian-Server und wählen Sie die Deaktivierungsoption. Aktivieren Sie ihn später dort wieder, falls Sie den vollständigen, ungefilterten Upstream-Toolsatz zurückbenötigen.

Starten Sie Claude Code (oder die MCP-Verbindung) nach der Registrierung neu bzw. verbinden Sie sich erneut, damit der neue Server übernommen wird. Tools dieses Proxys erscheinen unter dem Präfix atlassian-proxy (z. B. mcp__atlassian-proxy__getJiraIssue), bereits auf ALLOWED_TOOLS begrenzt und ohne cloudId/contentFormat/responseContentFormat.

Token-Ersparnis-Statistiken

Da Claude Code diesen Proxy verborgen ausführt und sein stderr im Chat nicht sichtbar ist, werden die Ersparnisse stattdessen in Dateien geschrieben:

• logs/token-savings.log – JSONL, eine Zeile pro tools/list/tools/call-Ereignis (tokensSavedIn, tokensSavedOut, laufende Summen).

• logs/stats-summary.txt – wird nach jedem Ereignis mit den aktuellen laufenden Summen überschrieben.

Es werden zwei Zahlen erfasst (beide sind Schätzungen – Zeichenanzahl / 4, kein echter Tokenizer, da kein Claude-Tokenizer eingebunden ist):

• Aus Claudes Kontext ferngehalten (tokensSavedIn): Tool-Listen-Kürzung (ALLOWED_TOOLS) plus aus Tool-Ergebnissen entferntes Rauschen (stripNoise).

• Claude musste nicht generieren (tokensSavedOut): die konstanten Parameter (cloudId, contentFormat, responseContentFormat), die der Proxy in Claudes Namen injiziert.

Um es live zu beobachten, öffnen Sie ein separates Terminal und verfolgen Sie die Zusammenfassungsdatei:

Get-Content logs\stats-summary.txt -Wait

Fehlerbehebung

• Hängt ohne ready-Meldung: npx -y mcp-remote ... wartet wahrscheinlich auf den OAuth-Browserablauf – prüfen Sie auf ein Browserfenster/einen Browser-Prompt.

• Tool in Claude nicht verfügbar: Bestätigen Sie, dass der Toolname in ALLOWED_TOOLS in index.js steht; alles, was nicht aufgeführt ist, wird aus tools/list herausgefiltert und bei tools/call abgelehnt.

Veraltete/abgelaufene Authentifizierung (401 Unauthorized oder could not resolve cloudId from getAccessibleAtlassianResources)

Die /mcp-Wiederverbindung von Claude Code startet nur den node index.js-stdio-Prozess neu – sie erzwingt keine erneute Authentifizierung. Das eigentliche OAuth-Token liegt eine Ebene tiefer und wird vom mcp-remote-Kindprozess auf der Festplatte unter ~/.mcp-auth/mcp-remote-<version>/<server-hash>_tokens.json zwischengespeichert, abhängig von der Upstream-Server-URL. Wenn dieses Token veraltet ist (abgelaufen, widerrufen oder bereits vor dem Neustart des node-Prozesses veraltet), schlägt jeder Tool-Aufruf mit 401/could not resolve cloudId fehl, egal wie oft Sie sich in Claude Code neu verbinden, da die Wiederverbindung diesen Cache nie berührt.

Vollständige Anleitung, in Reihenfolge:

1. Cache leeren: rm -rf ~/.mcp-auth (Windows: C:\Users\<you>\.mcp-auth). Dies löscht die zwischengespeicherte Client-Registrierung, den PKCE-Verifier und das Token für jeden mcp-remote-basierten Server auf dem Rechner – sicher, es ist reiner OAuth-Client-Zustand, nichts anderes hängt davon ab.

2. Eigenständig außerhalb von Claude Code neu authentifizieren, in einem eigenen Terminal:

   cd C:\Users\Dz\oktanetest\atlassian-proxy
   npx -y mcp-remote https://mcp.atlassian.com/v1/mcp --host 127.0.0.1

   Lassen Sie dies im Vordergrund (oder in einer beobachtbaren Hintergrund-Shell) laufen und schließen Sie die Browser-Anmeldung in Ihrem eigenen Tempo ab. Versuchen Sie nicht, sich zuerst durch erneutes Verbinden von atlassian-proxy in Claude Code zu authentifizieren – das eigene Verbindungs-Timeout von Claude Code konkurriert mit dem interaktiven OAuth-Ablauf, da main() von index.js seine eigene stdio-Seite erst öffnet, wenn die gesamte Upstream-mcp-remote-Verbindung (einschließlich Ihres Klickens durch den Browser) aufgelöst ist. Wenn Claude Code zuerst aufgibt, tötet es index.js und sein mcp-remote-Kind mitten im Handshake – der Browser zeigt möglicherweise weiterhin „Authorization successful!“, aber der Token-Austausch wird abgebrochen, bevor tokens.json geschrieben wird (Sie bleiben nur mit client_info.json/code_verifier.txt in ~/.mcp-auth zurück, ohne Token – prüfen Sie das, falls dies passiert). Wenn Sie mcp-remote zuerst eigenständig ausführen, wird dieser Wettlauf vollständig beseitigt; sobald es Proxy established successfully ausgibt (Exit-Code 0), ist das Token sicher zwischengespeichert.

3. Erst dann verbinden Sie atlassian-proxy in Claude Code erneut (/mcp). Es startet dasselbe mcp-remote, findet das nun gültige zwischengespeicherte Token und verbindet sich sofort ohne Browser-Schritt.

--host 127.0.0.1 in den Spawn-Argumenten von index.js (nicht der Upstream-mcp-remote-Standard) ist unter Windows erforderlich: Der lokale OAuth-Callback-Server von mcp-remote bindet nur 127.0.0.1, aber sein Standard-Redirect_uri-Hostname ist localhost. Auf einem Windows-Rechner, auf dem localhost zuerst zu ::1 aufgelöst wird (prüfen Sie mit Resolve-DnsName localhost), trifft die Post-Login-Weiterleitung des Browsers auf eine Adresse, auf der nichts lauscht – die Callback-Seite zeigt „Unable to connect“ und der Auth-Code bleibt hängen. Entfernen Sie dieses Flag nicht.

EADDRINUSE auf dem Callback-Port (z. B. listen EADDRINUSE: 127.0.0.1:3736), nachdem ein vorheriger Authentifizierungsversuch unterbrochen wurde: npx unter Windows tötet nicht immer den gesamten Kindprozessbaum, wenn sein Elternteil abgebrochen wird, sodass ein vorheriges mcp-remote verwaist zurückbleiben und den Port weiterhin belegen kann. Finden und beenden Sie es, bevor Sie es erneut versuchen:

Get-NetTCPConnection -LocalPort <port> | Select-Object OwningProcess
Stop-Process -Id <pid> -Force