Archery MCP 2FA

Dauerhafter Patch zur Unterstützung der Archery-TOTP-Zwei-Faktor-Authentifizierung (2FA) für @seaxlab/archery-mcp.

Dieses Projekt verbindet sich nicht direkt mit der Datenbank und umgeht auch nicht die Berechtigungs-, Maskierungs-, Ratenbegrenzungs- oder Audit-Mechanismen von Archery. Es erweitert lediglich den Anmeldevorgang, sodass Archery-Konten mit aktiviertem TOTP sich ebenfalls über den MCP-Dienst authentifizieren können.

Der aktuelle Patch gilt nur für @seaxlab/archery-mcp@3.0.2. Bevor Sie die Upstream-Abhängigkeit aktualisieren, prüfen Sie bitte, ob der Patch weiterhin kompatibel ist, und generieren Sie die Patch-Datei neu.

Funktionen

• Automatische Anmeldung mit dem in der Konfiguration hinterlegten Archery-Konto und Passwort beim Start.

• Bei Erkennung einer TOTP-Abfrage wird in einem interaktiven Terminal zur Eingabe des 6-stelligen Verifizierungscodes aufgefordert.

• Ohne interaktives Terminal wird ein MCP-Tool zur Authentifizierung bereitgestellt.

• Nach erfolgreicher Authentifizierung wird dieselbe Archery-Sitzung wiederverwendet.

• Der TOTP-Verifizierungscode wird nur für die aktuelle Anfrage verwendet und nicht in Konfigurationsdateien oder Metadaten-Caches geschrieben.

• Verwendung von patch-package zur automatischen Anwendung des Patches nach der Installation der Abhängigkeiten.

Related MCP server: auth-vault

Systemvoraussetzungen

• Node.js 24 oder höher.

• npm 10 oder höher.

• Ein erreichbarer Archery-Dienst; das Upstream-Paket gibt Unterstützung für Archery v1.8.5 an.

• Ein Archery-Konto mit aktiviertem TOTP oder ein normales Kontopasswort.

Schnellstart

1. Projekt abrufen und Abhängigkeiten installieren

git clone <repository-url>
cd archery-mcp-2fa
npm ci

Nach Abschluss von npm ci wendet das postinstall-Skript automatisch den 2FA-Patch aus patches/ an.

2. Konfigurationsdatei vorbereiten

Die Konfiguration kann auf Basis des vom Upstream-Paket bereitgestellten Beispiels erstellt werden:

mkdir -p ~/.config/archery-mcp
cp node_modules/@seaxlab/archery-mcp/config.example.toml \
  ~/.config/archery-mcp/pro.toml
chmod 600 ~/.config/archery-mcp/pro.toml

Bearbeiten Sie ~/.config/archery-mcp/pro.toml und füllen Sie mindestens Folgendes aus:

env = "pro"

[server]
host = "127.0.0.1"
port = 3000

[archery]
base_url = "https://archery.example.com"
username = "mcp_service"
password = "replace-with-a-strong-password"

[query]
default_limit = 100
max_limit = 500

[cache]
enabled = true
ttl_seconds = 604800
exclude_instance_names = []
exclude_instance_ids = []

Die Konfigurationsdatei enthält Klartext-Passwörter. Beschränken Sie die Dateiberechtigungen stets und committen Sie niemals echte Konfigurationen in das Versionsverzeichnis.

Eine vollständige Beschreibung der Konfigurationsoptionen finden Sie in der node_modules/@seaxlab/archery-mcp/README.md und der config.example.toml nach der Installation des Upstream-Projekts.

3. Dienst starten

Angabe der Konfigurationsdatei über den Befehlszeilenparameter:

npm start -- --config ~/.config/archery-mcp/pro.toml

Alternativ können auch Umgebungsvariablen verwendet werden:

ARCHERY_MCP_CONFIG=~/.config/archery-mcp/pro.toml npm start

Die Standard-MCP-Adresse lautet:

http://127.0.0.1:3000/mcp

Die Adresse für den Health-Check lautet:

http://127.0.0.1:3000/health

TOTP-Authentifizierungsablauf

Interaktives Terminal

Wenn für das Konto TOTP aktiviert ist, fordert das Terminal beim Start zur Eingabe auf:

archery-mcp [env=pro] Archery requires TOTP authentication
请输入当前 6 位 TOTP 验证码:

Geben Sie den aktuell im Authenticator angezeigten Verifizierungscode ein. Nach erfolgreicher Authentifizierung beginnt der Dienst, auf dem Port zu lauschen:

archery-mcp [env=pro] TOTP authentication succeeded
archery-mcp [env=pro] listening on http://127.0.0.1:3000/mcp

Bei einem ungültigen Verifizierungscode kann direkt erneut versucht werden. Nach Ablauf der Archery-Sitzung oder einem Neustart des Prozesses ist eine erneute Verifizierung erforderlich.

Ohne interaktives Terminal

Wenn der Dienst von einem Container, einer Hintergrundaufgabe oder einem Prozessmanager gestartet wird und kein interaktives Terminal verfügbar ist, startet der Dienst dennoch und registriert die folgenden MCP-Tools:

Authentifizierungsschritte:

1. Rufen Sie archery_auth_status auf.

2. Wenn two_factor_required: true zurückgegeben wird, lassen Sie sich vom Benutzer den aktuell im Authenticator angezeigten 6-stelligen Verifizierungscode geben.

3. Rufen Sie archery_submit_otp mit dem Parameter { "otp": "123456" } auf.

4. Bestätigen Sie, dass authenticated: true zurückgegeben wird, bevor Sie Abfrage- oder SQL-Überprüfungstools aufrufen.

Abgesehen von den beiden oben genannten Authentifizierungstools bleiben alle übrigen MCP-Tools identisch mit dem Upstream-@seaxlab/archery-mcp.

MCP-Client-Konfiguration

Verbindung mit einem MCP-Client, der Streamable HTTP unterstützt:

{
  "mcpServers": {
    "archery": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Codex kann in ~/.codex/config.toml konfiguriert werden:

[mcp_servers.archery]
url = "http://127.0.0.1:3000/mcp"

Claude Code kann über die Befehlszeile hinzugefügt werden:

claude mcp add --transport http archery http://127.0.0.1:3000/mcp

Projektstruktur

.
├── patches/
│   └── @seaxlab+archery-mcp+3.0.2.patch  # TOTP 支持补丁
├── package.json                           # 依赖和启动脚本
├── package-lock.json                      # 锁定依赖版本
└── README.md

Häufige Befehle

Bitte starten Sie nicht direkt mit npx -y @seaxlab/archery-mcp@3.0.2, da sonst das offizielle npm-Paket ohne den 2FA-Patch dieses Projekts ausgeführt wird.

Sicherheitshinweise

• Standardmäßig wird nur auf 127.0.0.1 gelauscht. Der MCP-HTTP-Endpunkt selbst verfügt über keine Authentifizierung und sollte nicht direkt im öffentlichen Netz freigegeben werden.

• Für Zugriffe über mehrere Maschinen hinweg fügen Sie auf der Reverse-Proxy-Ebene TLS, Zugriffsauthentifizierung und Netzwerkzugriffskontrolle hinzu.

• Das Archery-Passwort wird in der TOML-Konfiguration gespeichert. Setzen Sie chmod 600 und verwenden Sie ein dediziertes Dienstkonto mit minimalen Rechten.

• Committen Sie niemals echte Passwörter, TOTP-Verifizierungscodes, Sitzungs-Cookies, interne Archery-Adressen oder Produktionskonfigurationen in Repositorys, Issues oder Logs.

• TOTP wird über MCP-Anfragen übertragen. Stellen Sie bei Verwendung eines entfernten MCP-Clients sicher, dass der Kommunikationskanal vertrauenswürdig und verschlüsselt ist.

Kompatibilität und Wartung

Der Patch wirkt direkt auf die Build-Artefakte des Upstream-Pakets. Daher können Änderungen an der Upstream-Version dazu führen, dass der Patch nicht angewendet werden kann oder das Verhalten inkompatibel wird. Bei einem Upgrade wird Folgendes empfohlen:

1. Aktualisieren Sie die Version von @seaxlab/archery-mcp in der package.json.

2. Führen Sie npm install aus und prüfen Sie auf Patch-Konflikte.

3. Implementieren und verifizieren Sie die 2FA-Änderungen in node_modules/@seaxlab/archery-mcp erneut.

4. Führen Sie npx patch-package @seaxlab/archery-mcp aus, um einen neuen Patch zu generieren.

5. Verifizieren Sie den Authentifizierungsablauf sowohl im interaktiven Terminal als auch ohne interaktives Terminal.

Beiträge

Issues oder Pull Requests sind willkommen. Stellen Sie vor dem Einreichen von Code sicher, dass keine echten Konten, Passwörter, Verifizierungscodes, Cookies, internen Domänen oder andere sensible Informationen enthalten sind.

Danksagung und Hinweis

Dieses Projekt erstellt einen Patch auf Basis des öffentlich veröffentlichten Pakets von @seaxlab/archery-mcp und ist kein offizielles Projekt von Archery oder der Upstream-Paketbetreuer. Archery und zugehörige Namen sind Eigentum ihrer jeweiligen Inhaber.