LightNow-Proxy-Runtime
LightNow Proxy ist der MCP-Server-Prozess, den ein unterstützter AI-Client
startet. Aus einem clientseitigen LightNow-Eintrag werden die MCP-Server des
ausgewählten Runtime Profiles. Deren Commands, URLs und Secret-Werte müssen
nicht in die normale Client-Datei kopiert werden.
Request-Ablauf
Der Proxy läuft in derselben Ausführungsumgebung wie der AI-Client. Das kann eine Workstation, ein Remote-Development-Host, ein Server oder ein CI-Runner sein. Ein lokaler stdio-Upstream läuft ebenfalls dort. Ein HTTP-Upstream muss aus dieser Umgebung erreichbar sein.
Was auf dem Client-Host bleibt
- die AI-Client-Config,
- die client-spezifische Proxy-YAML unter
~/.lightnow/lightnow-proxy/, - lokale stdio-Prozesse und deren Dateisystemzugriff,
- Tool-Argumente und Tool-Ergebnisse sowie
- Resource-Inhalte und Workspace-Pfade.
Die generierte Proxy-YAML benennt Profil, Client, Transport, Registry API, Organisationskontext und Policy-Posture. Das vollständige Runtime Profile muss nicht in die Client-Datei kopiert werden.
Wie das Profil ausführbar wird
Beim Start verwendet der Proxy die authentifizierte LightNow-CLI-Session oder explizite Runtime-Credentials aus seiner Config. Er löst zuerst das ausgewählte Runtime Profile und danach jeden verknüpften oder benutzerdefinierten Server in eine Upstream-Config auf.
Ein Upstream besitzt eine von zwei unterstützten Runtime-Formen:
| Transport | Aktion des Proxys | Typischer Einsatz |
|---|---|---|
stdio | Startet einen lokalen Command mit festen Argumenten, Arbeitsverzeichnis und Umgebung | Lokale Tools und Server mit Dateisystemzugriff |
streamable-http | Öffnet eine MCP-Session zu einer erreichbaren HTTP-URL | Gehostete oder im Netzwerk erreichbare Server |
Können erforderliche Runtime Inputs nicht aufgelöst werden, schlägt der Proxy explizit fehl. Er erfindet keine unvollständige Server-Config und ersetzt den fehlenden Upstream nicht stillschweigend.
Wie MCP-Methoden geroutet werden
Der Proxy bündelt Tools, Resources und Prompts des aktiven Profils. Tool-Aliasse
erhalten das Präfix <upstream>__<tool>, damit gleiche Tool-Namen eindeutig
bleiben. Resource-URIs werden über eine LightNow-URI dargestellt, die die
Upstream-Identität erhält, während der eigentliche Inhalt im Request-Pfad bleibt.
Der Proxy verarbeitet heute diese MCP-Familien:
- Tools: auflisten und aufrufen,
- Resources: auflisten, lesen und Templates,
- Prompts: auflisten und abrufen sowie
- Logging- und Progress-Notifications, sofern der Upstream sie unterstützt.
Tool Discovery kann kurzzeitig gecacht werden, damit wiederholte Client-Starts zuverlässiger werden. Ein Health-Check führt aktive Discovery aus und meldet den tatsächlichen Upstream-Zustand, statt nur gecachten Metadaten zu vertrauen.
Runtime Events und Privacy-Grenze
Ist Telemetrie aktiviert, sendet LightNow Proxy reine Metadaten-Events für Lifecycle, MCP-Operationen und aktive Health-Checks. Events können Methode, Status, Dauer, Upstream-Alias, Transport, Tool-Name, Resource-URI, Anzahl der Elemente, Byte-Anzahl, Content Type und normalisierten Client-Kontext enthalten.
Runtime Events dürfen nicht enthalten:
- Tool-Argumente oder Tool-Ergebnisse,
- Resource-Inhalte,
- Workspace-Pfade, Git-Remotes oder Commit-Hashes,
- Secrets oder Authorization Header.
Diese Grenze erlaubt die Untersuchung eines fehlerhaften Pfads, ohne LightNow zum Speicher für MCP-Payloads zu machen.
Status und aktive Health-Checks
config-status prüft die erwarteten Client- und Proxy-Dateien. Der Command
startet keine Upstreams. lightnow-proxy --health löst das Profil auf, führt
Tool Discovery gegen jeden Upstream aus und liefert eines von drei Ergebnissen:
| Ergebnis | Bedeutung | Exit Code |
|---|---|---|
healthy | Das Profil wird aufgelöst und alle Upstreams antworten | 0 |
degraded | Der Proxy kann laufen, aber ein Upstream scheitert oder das Profil ist leer | 2 |
failed | Das ausgewählte Profil kann nicht aufgelöst werden | 1 |
lightnow config-status --client codex --json lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json
Fehlergrenzen
Nutze das Signal, das dem Fehler am nächsten liegt:
- Ein fehlender oder ungültiger Client-Eintrag gehört zum Client-Sync.
- Eine fehlende Proxy-YAML oder ein falsches Profil gehört zur lokalen Config.
- Fehler bei Authentifizierung oder Organisationskontext blockieren die Profilauflösung.
- Ein fehlerhafter Upstream-Health-Eintrag gehört zu Command, Credentials, Transport oder Verfügbarkeit dieses Servers.
- Ein clientseitiger MCP-Fehler nach erfolgreicher Discovery gehört zur gerouteten Methode oder Upstream-Implementierung.