Aurai Advisor (MCP-Berater)

Ein MCP-Dienst, der es lokaler KI ermöglicht, bei komplexen Programmierproblemen bei großen entfernten KI-Modellen nachzufragen.

Das aktuelle Repository entspricht der „langfristig nutzbaren“ Version, die nun über diese entscheidenden Fähigkeiten verfügt:

• Mehrstufige Beratung und Fortschrittsberichte

• sync_context Dateisynchronisierung

• Automatischer Upload von Code-/Konfigurationsdateien als Text

• Sitzungsisolierung (session_id)

• Persistenz des Verlaufs, Dateisperren, atomares Schreiben

• Automatische Zusammenfassung des Verlaufs

• Kürzung des Kontextfensters

Was ist neu in diesem Update

Dieses Haupt-Update konzentriert sich auf folgende Punkte:

• Fehler behoben, bei dem der Verlauf nach einem Neustart „wiederauferstand“, obwohl er gelöscht wurde

• session_id Sitzungsisolierung hinzugefügt, um Kontextvermischungen bei verschiedenen Problemen zu vermeiden

• Echte Konfigurationsmöglichkeiten für AURAI_TEMPERATURE, AURAI_MAX_ITERATIONS, AURAI_LOG_LEVEL usw. implementiert

• Sichergestellt, dass project_info und ergänzende Antworten tatsächlich an den übergeordneten Berater gesendet werden

• Dateisperren für den Verlauf und atomares Schreiben hinzugefügt, um das Risiko von beschädigten Verlaufsdateien bei gleichzeitigen Schreibvorgängen zu verringern

• Automatische Zusammenfassung des Verlaufs hinzugefügt, damit lange Sitzungen nicht zu umfangreich werden

• Kürzung des Kontextfensters hinzugefügt, AURAI_CONTEXT_WINDOW ist nun voll wirksam

• sync_context unterstützt jetzt die automatische Umwandlung von Code-/Konfigurationsdateien in sendbaren Text; manuelles Kopieren in .txt ist nicht mehr erforderlich

• README, Installationsanleitung und Benutzerhandbuch wurden überarbeitet; Installationsschritte stehen nun weiter oben

Wenn Sie dieses Repository zum ersten Mal verwenden, sind die zwei wichtigsten Punkte:

1. Lesen Sie zuerst die „Installationsanleitung“ unten

2. Codedateien können jetzt direkt an sync_context übergeben werden

Wofür ist es geeignet

Dieser MCP eignet sich für den Einsatz in Claude Code oder anderen MCP-Clients, die stdio unterstützen.

Typische Szenarien:

• Die lokale KI hat es bereits versucht, aber das Problem wurde nicht gelöst

• Fehlermeldungen, Code, Dokumentation und Konfiguration müssen gemeinsam an den „Senior-Berater“ übergeben werden

• Komplexe Fehlerbehebungen sollen in einen mehrstufigen Prozess aus „Frage -> Ausführung -> Bericht -> nächster Schritt“ umgewandelt werden

Funktionsübersicht

• consult_aurai Das primäre Beratungstool. Reichen Sie Fragen, Code-Snippets, Kontext und bereits versuchte Lösungen ein, um Analysen und Empfehlungen für den nächsten Schritt vom Senior-Berater zu erhalten.

• sync_context Synchronisiert Code- und Dokumentationskontext. Unterstützt jetzt nicht nur .txt/.md, sondern wandelt automatisch Textdateien wie .py/.js/.ts/.json/.yaml/.toml/.ini in sendbare Textinhalte um.

• report_progress Meldet die Ausführungsergebnisse an den Senior-Berater zurück, um die nächste Iterationsrunde fortzusetzen.

• get_status Zeigt den aktuellen Sitzungsstatus, die Anzahl der Verlaufsdatensätze sowie die Pfade zu Modell- und Verlaufsdateien an.

Installationsanleitung

Detailliertere Installationsschritte finden Sie unter:

• Claude Code Installationsanleitung

• Benutzerhandbuch

Hier ist der gängigste Installationsablauf:

1. Umgebung vorbereiten

# 需要 Python 3.10+
python --version

# 进入仓库目录
cd G:\codex\mcp-aurai-server

2. Virtuelle Umgebung erstellen und Abhängigkeiten installieren

python -m venv venv
venv\Scripts\activate
pip install -e ".[all-dev]"

3. MCP in Claude Code registrieren

claude mcp add --scope user --transport stdio aurai-advisor ^
  --env AURAI_API_KEY="your-api-key" ^
  --env AURAI_BASE_URL="https://api.example.com/v1" ^
  --env AURAI_MODEL="gpt-4o" ^
  -- "G:\codex\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"

Hinweise:

• AURAI_BASE_URL muss eine OpenAI-kompatible Schnittstellenadresse sein

• Die aktuelle Version behält nur den custom-Modus bei, AURAI_PROVIDER wird nicht mehr verwendet

• --scope user bedeutet, dass es in allen Projekten verfügbar ist, was am einfachsten ist

4. Installation überprüfen

claude mcp list
pytest

Erwartung:

• claude mcp list zeigt aurai-advisor an

• pytest läuft erfolgreich durch

Schnelleinstieg

Szenario 1: Direkt eine Frage stellen

consult_aurai(
    problem_type="runtime_error",
    error_message="启动时报 KeyError: api_key",
    code_snippet="config = load_config()\napi_key = config['api_key']",
    context={
        "file_path": "src/config.py",
        "terminal_output": "Traceback ...",
    }
)

Szenario 2: Erst Codedateien hochladen, dann fragen

sync_context(
    operation="incremental",
    files=["src/main.py", "config/settings.json", "README.md"],
    project_info={
        "project_name": "My Project",
        "tech_stack": "Python + FastAPI"
    }
)

consult_aurai(
    problem_type="runtime_error",
    error_message="请结合已同步文件帮我排查启动失败"
)

Hinweis:

• main.py muss nicht mehr manuell in main.txt kopiert werden

• Text-Codedateien werden automatisch in Text umgewandelt und gesendet

• Binärdateien werden übersprungen

Szenario 3: Mehrere Probleme parallel, Sitzungsisolierung nutzen

consult_aurai(
    problem_type="runtime_error",
    error_message="问题 A",
    session_id="issue-a"
)

consult_aurai(
    problem_type="design_issue",
    error_message="问题 B",
    session_id="issue-b"
)

Dies verhindert, dass sich verschiedene Probleme gegenseitig stören.

sync_context Dateiupload-Regeln

Wird direkt gesendet

• .md, .markdown, .mdx

• .txt

• Verschiedene Code- und Konfigurationstextdateien, zum Beispiel:

  • .py .js .ts .tsx

  • .json .yaml .yml .toml

  • .ini .cfg .env

  • .java .go .rs .cpp .cs

Wird automatisch konvertiert

• Dateien, die keine .txt/.md sind, deren Inhalt aber Text ist

• Es wird automatisch ein .txt oder .md Dateiname für den Versand generiert

• Vor dem Inhalt werden der „ursprüngliche Dateipfad“ und der „automatisch konvertierte Dateiname“ angefügt

Wird übersprungen

• Bilder

• Archivdateien

• Audio/Video

• Ausführbare Dateien

• Offensichtliche Binärinhalte

Wenn eine Dateigruppe sowohl Code als auch Bilder enthält:

• Code wird wie gewohnt hochgeladen

• Bilder werden als skipped_files markiert

• Die Synchronisierung als Ganzes ist weiterhin erfolgreich

Umgebungsvariablen

Erforderlich

Häufig verwendete Optionen

Wichtige Verhaltensweisen der aktuellen Version

1. Sitzungsisolierung

• Jede session_id hat ihren eigenen Verlauf

• Wenn nichts übergeben wird, wird default verwendet

• Verschiedene Sitzungen werden in unterschiedlichen Verlaufsdateien gespeichert, um Vermischungen zu vermeiden

2. Zusammenfassung des Verlaufs

• Älterer Verlauf wird automatisch in eine „Verlaufszusammenfassung“ komprimiert

• Die letzten Runden und der letzte sync_context werden nach Möglichkeit im Original beibehalten

• Dies reduziert die Kontextbelegung und schafft Platz für das aktuelle Problem

3. Kürzung des Kontextfensters

• System-Prompts werden bevorzugt beibehalten

• Der letzte sync_context wird bevorzugt beibehalten

• Die letzten Verlaufsrunden werden nach Möglichkeit beibehalten

• Bei Bedarf wird die aktuelle Ausgabelänge automatisch reduziert, um das Gesamtfenster nicht zu überschreiten

4. Stabilere Verlaufsdateien

• Beim Speichern des Verlaufs wird eine Sperrdatei verwendet, um gleichzeitige Schreibfehler zu vermeiden

• Das Schreiben erfolgt über eine temporäre Datei, die dann ersetzt wird, um unvollständige JSON-Dateien zu vermeiden

Testen

pytest

Die aktuellen Schwerpunkte umfassen:

• Löschen und Persistenz des Verlaufs

• Sitzungsisolierung

• Automatischer Textkonvertierungs-Upload

• Verlaufs-Sperren und atomares Schreiben

• Verlaufszusammenfassung

• Kürzung des Kontextfensters

Dokumentation

• Claude Code Installationsanleitung

• Benutzerhandbuch

• Entwicklerdokumentation

Häufig gestellte Fragen

Warum hat der Senior-Berater meine hochgeladenen Codedateien nicht erhalten?

Ältere Versionen erforderten eine manuelle Konvertierung in .txt. Die aktuelle Version unterstützt die automatische Konvertierung von Textdateien.

Falls sie immer noch nicht ankommen, prüfen Sie zuerst:

• Existiert der Dateipfad?

• Ist die Datei binär?

• Was steht in uploaded_files / skipped_files der sync_context-Antwort?

Warum beeinflussen sich verschiedene Probleme gegenseitig?

Wenn Sie eine vollständige Isolierung wünschen, übergeben Sie für verschiedene Probleme unterschiedliche session_ids.

Warum sieht die Verlaufsdatei kürzer aus?

Das ist die Verlaufszusammenfassung bei der Arbeit. Der alte Verlauf wurde in ein Protokoll komprimiert; er ist nicht verloren, sondern wurde durch ein kontextschonenderes „Sitzungsprotokoll“ ersetzt.