Zava Relocation MCP UI Demo

Zava Relocation Inc. hilft Mitarbeitern, für einen neuen Job umzuziehen. Dieses Projekt ist eine Referenzdemo für den Aufbau einer interaktiven MCP-App mit MCP-UI, einem lokalen Qwen2.5 7B-Modell und einem synchronisierten Konversations-Intake-Formular.

Der Benutzer kann mit Ava chatten, ein Angebotsschreiben hochladen oder das Profil direkt bearbeiten. Extrahierte Informationen werden sofort auf das Formular angewendet und hervorgehoben, damit der Benutzer überprüfen kann, was sich geändert hat.

Für eine kundenorientierte Lehr-Walkthrough siehe den dedizierten MCP UI + LLM Form-Fill-Leitfaden.

Was die Demo demonstriert

• Chatgesteuerte Formularausfüllung mit Live-Feldaktualisierungen

• Optionaler Browser-Sprachmodus: Sprich mit Ava und höre Qwen-Antworten laut

• PDF- und DOCX-Angebotsschreiben-Extraktion im Browser

• Lokale Interpretation mit Qwen2.5 7B über Foundry Local

• Fünf Profilabschnitte: Kontakt, Beschäftigung, Umzug, Umzugslogistik und Präferenzen

• Fundierte Umzugsoptionen- und Erstattungsrichtlinien aus dem fiktiven Contoso-Policy-PDF

• Fortschrittsverfolgung, hervorgehobene KI-Updates, Zurücksetzen und Abschlussstatus

• Responsive Desktop- und Mobile-Layouts

• MCP-Apps-Ressourcen-/Tool-Verknüpfung über @mcp-ui/server und @modelcontextprotocol/ext-apps

• Ein Produktions-Build, der die UI in eine einzige HTML-Ressource einbettet

Demo-Grenze: Dies ist ein lokaler Prototyp. Er speichert keine Umzugsfälle, authentifiziert keine Benutzer und übermittelt keine Daten an ein Produktions-HR-System. Die Beispiel-PDFs in sample-documents/ enthalten fiktive Daten.

Related MCP server: Docalyze

Architektur

MCP Apps host
      |
      | Streamable HTTP: POST /mcp
      v
Node + Express MCP server
      |-- start_relocation_intake tool
      |-- ui://zava-relocation/intake resource
      |-- POST /api/chat
      v
Foundry Local (same machine)
      |
      v
Qwen2.5 7B

Browser UI
  |-- PDF.js / Mammoth extract document text locally
  |-- regex extractor gives immediate form updates
  |-- /api/chat sends text and current form to local Qwen

Es gibt zwei Möglichkeiten, die UI zu verwenden:

1. Standalone-Modus: Vite serviert die React-Anwendung unter http://localhost:5173.

2. MCP-App-Modus: Ein MCP-Apps-kompatibler Host verbindet sich mit http://localhost:3001/mcp, entdeckt start_relocation_intake und rendert die verknüpfte ui://zava-relocation/intake-Ressource.

Wie MCP-UI genutzt wird

Dieses Projekt verwendet das von MCP-UI empfohlene MCP-Apps-Muster:

1. server/index.ts erstellt einen McpServer und einen StreamableHTTPServerTransport.

2. Das Produktions-dist/index.html wird mit createUIResource in eine UI-Ressource geladen.

3. registerAppResource veröffentlicht diese Ressource unter ui://zava-relocation/intake.

4. registerAppTool stellt start_relocation_intake bereit und verknüpft es mit der UI über:

   _meta: {
     ui: { resourceUri: relocationUI.resource.uri },
   }

5. Die eingebettete UI signalisiert Bereitschaft mit ui-lifecycle-iframe-ready und kann Host-Nachrichten mit window.parent.postMessage senden.

Der wichtige Unterschied besteht darin, dass der MCP-Server das Formular nicht selbst rendert. Er registriert das Tool und die UI-Ressource; der MCP-Apps-Host entscheidet, wo und wie diese Ressource angezeigt wird.

Foundry Local und Qwen2.5 7B

Der Assistent verwendet Qwen2.5 7B über Foundry Local. Foundry Local läuft auf derselben Maschine wie dieser Node-Server und stellt einen OpenAI-kompatiblen lokalen Chat-Completions-Endpunkt bereit. Es ist kein Cloud-Modell-Fallback konfiguriert.

Voraussetzungen

Die Unterstützung von Foundry Local hängt von der Host-Maschine ab. Unter Windows dokumentiert Microsoft Windows 11 24H2 oder später, .NET 9 oder später und eine DirectX-12-fähige GPU für die Windows-ML-Laufzeit.

Installiere die Foundry-Local-CLI:

winget install Microsoft.FoundryLocal

Schließe und öffne PowerShell erneut und überprüfe dann die CLI:

foundry --version

Liste die im lokalen Katalog verfügbaren Modell-Aliase auf:

foundry model list

Starte oder lade das Qwen-Modell mit dem Alias, der vom Katalog angezeigt wird. Der erwartete Demo-Alias ist:

foundry model run qwen2.5-7b

Halte Foundry Local während der Nutzung der Demo am Laufen. Der aktuelle Foundry-Local-Service-Endpunkt für dieses Projekt ist:

http://127.0.0.1:61563/v1/chat/completions

Wenn der installierte Katalog einen anderen Alias oder Port verwendet, konfiguriere den Node-Server, bevor du ihn startest:

$env:FOUNDRY_LOCAL_ENDPOINT = "http://127.0.0.1:<actual-port>/v1/chat/completions"
$env:FOUNDRY_LOCAL_MODEL = "qwen2.5-7b-instruct-cuda-gpu"

Foundry Local weist den Service-Port dynamisch zu. Verwende foundry service status oder foundry service list, um den aktiven Service zu überprüfen, und verwende GET http://127.0.0.1:<port>/openai/models, um verfügbare Modell-IDs aufzulisten. Die genaue Modell-ID kann je nach Hardware variieren; auf dieser Maschine ist das verfügbare Qwen-GPU-Modell qwen2.5-7b-instruct-cuda-gpu.

Was das Modell erhält

server/foundryLocal.ts sendet an Qwen:

• Die neueste Benutzernachricht oder eine Dokumentprüfungsanweisung

• Den aktuellen Formularzustand

• Bis zu 8.000 Zeichen extrahierten Dokumenttext

Die Systemaufforderung fordert Qwen auf, JSON in dieser Form zurückzugeben:

{
  "reply": "I found your new employer and start date.",
  "fields": {
    "employer": "Northstar Analytics",
    "role": "Senior Product Manager",
    "startDate": "2026-10-07"
  }
}

Nur auf der Zulassungsliste stehende Formularschlüssel werden vom Server akzeptiert. Das Modell kann dem Client-Zustand keine beliebigen Felder hinzufügen.

Sprachmodus

Qwen2.5 7B bleibt ein reines Textmodell. Der Sprachmodus nutzt Browserfunktionen rund um die bestehende Text-Pipeline:

microphone
  -> browser SpeechRecognition
  -> transcript
  -> POST /api/chat
  -> Foundry Local + Qwen
  -> text reply and form fields
  -> browser SpeechSynthesis
  -> spoken Ava response

Klicke im Composer auf die Mikrofontaste, um zu sprechen. Wenn die Erkennung endet, wird das Transkript über denselben Chat-Flow übermittelt, der auch für getippte Nachrichten verwendet wird. Das Ava-Sprache an/aus-Steuerelement aktiviert oder deaktiviert gesprochene Antworten, Sprache lässt dich eine installierte Browserstimme wählen, und Ava stoppen unterbricht die aktuelle Antwort. Die App bevorzugt natürliche englische Microsoft/Edge-Stimmen, wenn verfügbar, wie Ava, Jenny, Aria oder Sonia. Chrome und Edge bieten die beste Unterstützung; Mikrofonberechtigung ist erforderlich und Spracheingabe benötigt localhost oder HTTPS. Die Sprachqualität hängt von den im Browser installierten und bereitgestellten Stimmen ab.

Die Spracheingabe verwendet einen geführten Ein-Feld-nach-dem-anderen-Flow. Die App identifiziert das nächste unvollständige Pflichtfeld, bittet Qwen, sich auf dieses Feld zu konzentrieren, rückt nach der Antwort den aktiven Formularabschnitt vor und spricht eine kurze nächste Frage. So bleibt jede Sprachrunde leicht zu merken. Getippter Chat bleibt frei formulierbar.

Dokument-Parsing-Flow

Der Browser verarbeitet die Originaldatei; die Datei selbst wird nicht in einen Cloud-Dienst hochgeladen:

1. src/App.tsx validiert die Erweiterung und das 10-MB-Limit.

2. src/documentParser.ts verwendet PDF.js für PDFs und Mammoth für DOCX-Dateien.

3. Der extrahierte Text wird zur Dokumentinterpretation über POST /api/chat an lokales Qwen gesendet.

4. Qwen gibt strukturierte Felder zurück. Die UI verwendet eine konsistente Dokumentprüfungsnachricht, die den Benutzer auffordert, das Formular zu überprüfen und fehlende Informationen manuell zu vervollständigen; sie listet fehlende Felder nicht auf.

5. Die Modellfelder werden im Formular angewendet und hervorgehoben.

Fundierte Logistik-Walkthrough

Lade contoso-moving-offers-and-reimbursement-guide.pdf hoch und stelle Ava dann Fragen wie „Welche Option ist am besten für einen Umzug über 250 Meilen?“ oder „Kann ich für 150 Meilen einen Miet-LKW verwenden?“ Der Browser behält den extrahierten Richtlinientext als Grundlage für spätere Chat-Runden, und das Modell wird angewiesen, Richtlinienfragen nur aus diesem Text zu beantworten. Der Abschnitt „Umzugslogistik“ erfasst die gewählte Methode, die ungefähre Entfernung, den Erstattungsweg und Notizen.

Die browserbasierten PDF.js- und Mammoth-Bibliotheken sind nur Text-Extraktionswerkzeuge; sie entscheiden nicht, welche Werte in das Umzugsformular gehören. Foundry Local/Qwen ist die Quelle der Wahrheit für die PDF/DOCX-Feldextraktion. Wenn das Modell nicht verfügbar ist, meldet die UI den Fehler, anstatt Dokumentfelder stillschweigend mit einem Nicht-LLM-Parser zu füllen.

Code-Brotkrumen

Installation und Ausführung

Installiere Node-Abhängigkeiten:

npm install

Standalone-Entwicklungsmodus

Starte Vite und den MCP-Server zusammen:

npm run dev

Öffne:

http://localhost:5173

Der Vite-/api-Proxy leitet lokale Modellanfragen an Port 3001 weiter.

MCP-Apps-Modus

Baue zuerst die UI. Der MCP-Server bettet das resultierende dist/index.html ein:

npm run build
npm start

Konfiguriere den MCP-Apps-kompatiblen Host mit:

http://localhost:3001/mcp

Rufe dann auf:

start_relocation_intake

Der Server stellt auch einen einfachen Health-Check bereit:

http://localhost:3001/health

Demo-Workflow

1. Starte Foundry Local und stelle das Qwen-Modell bereit.

2. Führe npm run dev aus.

3. Klicke auf einen Schnellprompt oder tippe eine Umzugsnachricht.

4. Beobachte, wie die passenden Felder ausgefüllt und hervorgehoben werden.

5. Lade eines der PDFs in sample-documents/ hoch.

6. Überprüfe die extrahierten und modellangereicherten Felder.

7. Verwende Demo zurücksetzen, um in einen leeren Zustand zurückzukehren.

Nützliche Chat-Prompts:

• Ich ziehe von Seattle nach Austin für eine Rolle bei Contoso.

• Meine Familie hat 3 Personen.

• Arbeitgeber: Fabrikam

• Position: Senior Product Manager

• Ich brauche temporären Wohnraum.

Fehlerbehebung

Could not connect to Foundry Local

Überprüfe, dass Foundry Local läuft, dass das Modell heruntergeladen/geladen wurde und dass der Endpunkt mit FOUNDRY_LOCAL_ENDPOINT übereinstimmt.

Model not found

Führe foundry model list aus und setze FOUNDRY_LOCAL_MODEL auf einen Alias im installierten Katalog.

Der MCP-Server meldet Missing dist/index.html

Führe aus:

npm run build

vor npm start.

Das Formular findet keine Felder in einem Dokument

Das PDF muss auswählbaren Text enthalten. Gescannte/nur-Bild-PDFs benötigen OCR, bevor PDF.js nützlichen Text extrahieren kann. Beschriftete Werte wie Employee name:, Email address:, New employer:, Job title:, Start date:, Moving from: und Moving to: sind für den deterministischen Extraktor am einfachsten zu erkennen.

Skripte

Um das fiktive Contoso-Policy-PDF neu zu generieren, installieren Sie die Skriptabhängigkeit und führen Sie den Generator aus:

python -m pip install -r scripts/requirements.txt
python scripts/generate_contoso_policy_pdf.py