Zava Relocation MCP UI Demo

Zava Relocation Inc. は、新しい仕事のために従業員の引っ越しを支援します。このプロジェクトは、MCP-UI、ローカルの Qwen2.5 7B モデル、および同期された会話型インテークフォームを使用して、インタラクティブな MCP App を構築するためのリファレンスデモです。

ユーザーは Ava とチャットしたり、オファーレターをアップロードしたり、プロフィールを直接編集したりできます。抽出された情報は即座にフォームに適用され、変更内容を確認できるようにハイライト表示されます。

顧客向けの教育用ウォークスルーについては、専用の MCP UI + LLM フォーム入力ガイド を参照してください。

デモで実証されること

• チャット駆動のフォーム入力とライブフィールド更新

• オプションのブラウザ音声モード: Ava に話しかけ、Qwen の応答を音声で聞く

• ブラウザでの PDF および DOCX オファーレターの抽出

• Foundry Local による Qwen2.5 7B でのローカル解釈

• 5 つのプロフィールセクション: 連絡先、雇用、引っ越し、引っ越しロジスティクス、および設定

• 架空の Contoso ポリシー PDF に基づく引っ越しオプションと払い戻しのガイダンス

• 進捗追跡、ハイライトされた AI 更新、リセット、完了状態

• レスポンシブなデスクトップおよびモバイルレイアウト

• @mcp-ui/server と @modelcontextprotocol/ext-apps による MCP Apps リソース/ツールの連携

• UI を 1 つの HTML リソースにインライン化する本番ビルド

デモの境界: これはローカルプロトタイプです。引っ越しケースを永続化せず、ユーザーを認証せず、本番 HR システムにデータを送信しません。sample-documents/ 内のサンプル PDF には架空のデータが含まれています。

Related MCP server: Docalyze

アーキテクチャ

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

UI を使用する方法は 2 つあります:

1. スタンドアロンモード: Vite が http://localhost:5173 で React アプリケーションを提供します。

2. MCP App モード: MCP Apps 互換ホストが http://localhost:3001/mcp に接続し、start_relocation_intake を検出し、リンクされた ui://zava-relocation/intake リソースをレンダリングします。

MCP-UI の活用方法

このプロジェクトは、MCP-UI が推奨する MCP Apps パターンを使用しています:

1. server/index.ts は McpServer と StreamableHTTPServerTransport を作成します。

2. 本番の dist/index.html は、createUIResource を使用して UI リソースに読み込まれます。

3. registerAppResource はそのリソースを ui://zava-relocation/intake に公開します。

4. registerAppTool は start_relocation_intake を公開し、次のように UI にリンクします:

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

5. 埋め込まれた UI は ui-lifecycle-iframe-ready で準備完了を通知し、window.parent.postMessage でホストメッセージを送信できます。

重要な違いは、MCP サーバーがフォーム自体をレンダリングしないことです。ツールと UI リソースを登録するだけで、MCP Apps ホストがそのリソースをどこにどのように表示するかを決定します。

Foundry Local と Qwen2.5 7B

アシスタントは Foundry Local 経由の Qwen2.5 7B を使用します。Foundry Local はこの Node サーバーと同じマシン上で動作し、OpenAI 互換のローカルチャット完了エンドポイントを公開します。クラウドモデルのフォールバックは設定されていません。

前提条件

Foundry Local のサポートはホストマシンに依存します。Windows では、Microsoft は Windows 11 24H2 以降、.NET 9 以降、および Windows ML ランタイム用の DirectX 12 対応 GPU を文書化しています。

Foundry Local CLI をインストールします:

winget install Microsoft.FoundryLocal

PowerShell を閉じて再度開き、CLI を確認します:

foundry --version

ローカルカタログで利用可能なモデルエイリアスを一覧表示します:

foundry model list

カタログに表示されたエイリアスを使用して Qwen モデルを起動またはダウンロードします。期待されるデモエイリアスは次のとおりです:

foundry model run qwen2.5-7b

デモを使用している間は Foundry Local を実行したままにしてください。このプロジェクトの現在の Foundry Local サービスエンドポイントは次のとおりです:

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

インストールされたカタログが別のエイリアスまたはポートを使用している場合は、起動前に Node サーバーを設定してください:

$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 はサービスポートを動的に割り当てます。foundry service status または foundry service list を使用してアクティブなサービスを確認し、GET http://127.0.0.1:<port>/openai/models を使用して利用可能なモデル ID を一覧表示します。正確なモデル ID はハードウェアによって異なる場合があります。このマシンでは、利用可能な Qwen GPU モデルは qwen2.5-7b-instruct-cuda-gpu です。

モデルが受け取るもの

server/foundryLocal.ts は Qwen に送信します:

• 最新のユーザーメッセージまたはドキュメントレビューの指示

• 現在のフォーム状態

• 抽出されたドキュメントテキストの最大 8,000 文字

システムプロンプトは Qwen に次の形式の JSON を返すように要求します:

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

サーバーは許可リストに登録されたフォームキーのみを受け入れます。モデルはクライアント状態に任意のフィールドを追加できません。

音声モード

Qwen2.5 7B はテキストのみのモデルのままです。音声モードは、既存のテキストパイプラインの周りでブラウザの機能を使用します:

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

コンポーザーのマイクボタンをクリックして話します。認識が終了すると、トランスクリプトは入力されたメッセージと同じチャットフローで送信されます。Ava 音声オン/オフ コントロールは音声応答を有効または無効にし、Voice はインストールされているブラウザの音声を選択でき、Stop Ava は現在の応答を中断します。アプリは、利用可能な場合、Ava、Jenny、Aria、Sonia などの Microsoft/Edge の自然な英語音声を優先します。Chrome と Edge が最良のサポートを提供します。マイクの許可が必要で、音声入力には localhost または HTTPS が必要です。音声品質は、ブラウザにインストールされ公開されている音声に依存します。

音声入力は、一度に 1 つのフィールドをガイドするフローを使用します。アプリは次の未完了の必須フィールドを特定し、Qwen にそのフィールドに集中するよう要求し、回答後にアクティブなフォームセクションを進め、短い次の質問を 1 つ話します。これにより、各音声ターンを覚えやすくします。入力されたチャットは自由形式のままです。

ドキュメント解析フロー

ブラウザが元のファイルを処理します。ファイル自体はクラウドサービスにアップロードされません:

1. src/App.tsx は拡張子と 10 MB の制限を検証します。

2. src/documentParser.ts は PDF には PDF.js を、DOCX ファイルには Mammoth を使用します。

3. 抽出されたテキストは、ドキュメント解釈のために POST /api/chat を通じてローカルの Qwen に送信されます。

4. Qwen は構造化されたフィールドを返します。UI は、ユーザーにフォームを確認し、不足している情報を手動で完了するように指示する一貫したドキュメントレビューメッセージを使用します。不足しているフィールドを列挙することはありません。

5. モデルのフィールドがフォームに適用され、ハイライト表示されます。

根拠に基づくロジスティクスのウォークスルー

contoso-moving-offers-and-reimbursement-guide.pdf をアップロードし、Ava に「250 マイルの引っ越しにはどのオプションが最適ですか？」や「150 マイルでレンタルトラックを使用できますか？」などの質問をします。ブラウザは抽出されたポリシーテキストを後続のチャットターンの根拠として保持し、モデルはそのテキストからのみポリシー質問に答えるように指示されます。Moving logistics セクションは、選択した方法、おおよその距離、払い戻し経路、およびメモを取得します。

ブラウザ側の PDF.js および Mammoth ライブラリはテキスト抽出ユーティリティのみであり、どの値が引っ越しフォームに属するかを決定しません。PDF/DOCX フィールド抽出の真実の源は Foundry Local/Qwen です。モデルが利用できない場合、UI は非 LLM パーサーでドキュメントフィールドを静かに埋める代わりにエラーを報告します。

コードの手がかり

インストールと実行

Node の依存関係をインストールします:

npm install

スタンドアロン開発モード

Vite と MCP サーバーを一緒に起動します:

npm run dev

開く:

http://localhost:5173

Vite の /api プロキシはローカルモデルリクエストをポート 3001 に転送します。

MCP Apps モード

最初に UI をビルドします。MCP サーバーは結果の dist/index.html を埋め込みます:

npm run build
npm start

MCP Apps 互換ホストを次のように設定します:

http://localhost:3001/mcp

次に呼び出します:

start_relocation_intake

サーバーは基本的なヘルスチェックも公開します:

http://localhost:3001/health

デモのワークフロー

1. Foundry Local を起動し、Qwen モデルを利用可能にします。

2. npm run dev を実行します。

3. クイックプロンプトをクリックするか、引っ越しメッセージを入力します。

4. 一致するフィールドが入力され、ハイライトされるのを確認します。

5. sample-documents/ 内の PDF の 1 つをアップロードします。

6. 抽出され、モデルで強化されたフィールドを確認します。

7. デモのリセット を使用して空の状態に戻します。

便利なチャットプロンプト:

• I'm moving from Seattle to Austin for a role at Contoso.

• My family has 3 people.

• Employer: Fabrikam

• Position: Senior Product Manager

• I need temporary housing.

トラブルシューティング

Could not connect to Foundry Local

Foundry Local が実行されていること、モデルがダウンロード/ロードされていること、エンドポイントが FOUNDRY_LOCAL_ENDPOINT と一致していることを確認してください。

Model not found

foundry model list を実行し、FOUNDRY_LOCAL_MODEL をインストールされたカタログ内のエイリアスに設定します。

MCP サーバーが Missing dist/index.html と表示する

実行:

npm run build

npm start の前に。

フォームがドキュメント内のフィールドを見つけられない

PDF には選択可能なテキストが含まれている必要があります。スキャンされた画像のみの PDF は、PDF.js が有用なテキストを抽出する前に OCR が必要です。Employee name:、Email address:、New employer:、Job title:、Start date:、Moving from:、Moving to: などのラベル付き値は、決定的な抽出器が最も認識しやすいものです。

スクリプト

架空の Contoso ポリシー PDF を再生成するには、スクリプトの依存関係をインストールしてジェネレーターを実行します。

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