Zava Relocation MCP UI Demo

Zava Relocation Inc. помогает сотрудникам переезжать на новую работу. Этот проект — эталонная демонстрация создания интерактивного MCP-приложения с помощью MCP-UI, локальной модели Qwen2.5 7B и синхронизированной диалоговой формы ввода данных.

Пользователь может общаться с Авой, загружать письмо с предложением о работе или редактировать профиль напрямую. Извлечённая информация немедленно применяется к форме и выделяется, чтобы пользователь мог проверить изменения.

Пошаговое руководство для обучения клиентов см. в отдельном руководстве по заполнению форм MCP UI + LLM.

Что демонстрирует демо

• Заполнение формы через чат с обновлением полей в реальном времени

• Необязательный голосовой режим в браузере: говорите с Авой и слушайте ответы Qwen вслух

• Извлечение данных из писем о предложении работы в форматах PDF и DOCX в браузере

• Локальная интерпретация с помощью Qwen2.5 7B через Foundry Local

• Пять разделов профиля: контакты, трудоустройство, переезд, логистика переезда и предпочтения

• Обоснованные рекомендации по вариантам переезда и возмещению расходов из вымышленного PDF-документа политики Contoso

• Отслеживание прогресса, выделенные обновления ИИ, сброс и состояние завершения

• Адаптивные настольная и мобильная версии

• Связывание ресурсов/инструментов MCP Apps через @mcp-ui/server и @modelcontextprotocol/ext-apps

• Продакшен-сборка, встраивающая интерфейс в один HTML-ресурс

Границы демо: это локальный прототип. Он не сохраняет кейсы переезда, не аутентифицирует пользователей и не отправляет данные в корпоративную HR-систему. Образцы PDF-файлов в sample-documents/ содержат вымышленные данные.

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

Есть два способа использования интерфейса:

1. Автономный режим: Vite обслуживает приложение React по адресу http://localhost:5173.

2. Режим MCP-приложения: совместимый с MCP Apps хост подключается к http://localhost:3001/mcp, обнаруживает start_relocation_intake и отображает связанный ресурс ui://zava-relocation/intake.

Как используется MCP-UI

В этом проекте используется шаблон MCP Apps, рекомендованный MCP-UI:

1. server/index.ts создаёт McpServer и StreamableHTTPServerTransport.

2. Продакшен-сборка dist/index.html загружается в ресурс интерфейса с помощью createUIResource.

3. registerAppResource публикует этот ресурс по адресу ui://zava-relocation/intake.

4. registerAppTool открывает start_relocation_intake и связывает его с интерфейсом с помощью:

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

5. Встроенный интерфейс сигнализирует о готовности с помощью ui-lifecycle-iframe-ready и может отправлять сообщения хосту через window.parent.postMessage.

Важное отличие в том, что MCP-сервер не отображает форму сам. Он регистрирует инструмент и ресурс интерфейса; хост MCP Apps решает, где и как отображать этот ресурс.

Foundry Local и Qwen2.5 7B

Ассистент использует Qwen2.5 7B через Foundry Local. Foundry Local работает на той же машине, что и этот Node-сервер, и предоставляет совместимую с OpenAI локальную конечную точку чат-завершений. Облачный резервный вариант модели не настроен.

Предварительные требования

Поддержка Foundry Local зависит от хост-машины. В Windows корпорация Майкрософт документирует Windows 11 24H2 или новее, .NET 9 или новее и графический процессор с поддержкой DirectX 12 для среды выполнения Windows ML.

Установите CLI Foundry Local:

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, чтобы вывести список доступных идентификаторов моделей. Точный идентификатор модели может различаться в зависимости от оборудования; на этой машине доступная модель 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

Нажмите кнопку микрофона в компоновщике, чтобы говорить. Когда распознавание завершится, стенограмма отправляется через тот же чат-поток, что и набранные сообщения. Переключатель Голос Авы вкл/выкл включает или отключает голосовые ответы, Голос позволяет выбрать установленный голос браузера, а Остановить Аву прерывает текущий ответ. Приложение предпочитает естественные английские голоса Microsoft/Edge, если они доступны, например Ава, Дженни, Ария или Соня. Chrome и Edge обеспечивают наилучшую поддержку; требуется разрешение на доступ к микрофону, а для голосового ввода нужен localhost или HTTPS. Качество голоса зависит от голосов, установленных и предоставляемых браузером.

Голосовой ввод использует управляемый поток по одному полю за раз. Приложение определяет следующее незаполненное обязательное поле, просит Qwen сосредоточиться на этом поле, переходит к следующему разделу формы после ответа и произносит один короткий следующий вопрос. Это позволяет легко запоминать каждый голосовой ход. Набранный чат остаётся свободным.

Процесс разбора документов

Браузер обрабатывает исходный файл; сам файл не загружается в облачный сервис:

1. src/App.tsx проверяет расширение и лимит в 10 МБ.

2. src/documentParser.ts использует PDF.js для PDF-файлов и Mammoth для файлов DOCX.

3. Извлечённый текст отправляется в локальную Qwen через POST /api/chat для интерпретации документа.

4. Qwen возвращает структурированные поля. Интерфейс использует единое сообщение о проверке документа, предлагающее пользователю просмотреть форму и вручную заполнить недостающую информацию; он не перечисляет недостающие поля.

5. Поля модели применяются и выделяются в форме.

Пошаговое руководство по логистике

Загрузите contoso-moving-offers-and-reimbursement-guide.pdf, затем задайте Аве такие вопросы, как «Какой вариант лучше всего подходит для переезда на 250 миль?» или «Могу ли я использовать арендованный грузовик на 150 миль?» Браузер сохраняет извлечённый текст политики в качестве основы для последующих сообщений чата, и модели предписано отвечать на вопросы о политике только на основе этого текста. В разделе «Логистика переезда» фиксируются выбранный способ, примерное расстояние, путь возмещения расходов и примечания.

Браузерные библиотеки PDF.js и Mammoth — это только утилиты извлечения текста; они не решают, какие значения должны попасть в форму переезда. Foundry Local/Qwen является источником истины для извлечения полей из PDF/DOCX. Если модель недоступна, интерфейс сообщает об ошибке, а не молча заполняет поля документа с помощью парсера, не основанного на LLM.

Хлебные крошки кода

Установка и запуск

Установите зависимости Node:

npm install

Автономный режим разработки

Запустите Vite и MCP-сервер вместе:

npm run dev

Откройте:

http://localhost:5173

Прокси Vite /api пересылает запросы локальной модели на порт 3001.

Режим MCP Apps

Сначала соберите интерфейс. 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. Загрузите один из PDF-файлов в sample-documents/.

6. Просмотрите извлечённые и обогащённые моделью поля.

7. Используйте Сбросить демо, чтобы вернуться в пустое состояние.

Полезные подсказки для чата:

• Я переезжаю из Сиэтла в Остин на должность в Contoso.

• Моя семья состоит из 3 человек.

• Работодатель: Fabrikam

• Должность: старший менеджер по продукту

• Мне нужно временное жильё.

Устранение неполадок

Не удаётся подключиться к Foundry Local

Проверьте, что Foundry Local запущен, модель загружена/загружена, а конечная точка соответствует FOUNDRY_LOCAL_ENDPOINT.

Модель не найдена

Выполните foundry model list и установите FOUNDRY_LOCAL_MODEL на псевдоним в установленном каталоге.

MCP-сервер сообщает Missing dist/index.html

Выполните:

npm run build

перед npm start.

Форма не находит поля в документе

PDF-файл должен содержать выделяемый текст. Для отсканированных PDF-файлов и PDF-файлов, содержащих только изображения, требуется OCR, прежде чем PDF.js сможет извлечь полезный текст. Подписанные значения, такие как Имя сотрудника:, Адрес электронной почты:, Новый работодатель:, Должность:, Дата начала:, Переезд из: и Переезд в:, легче всего распознаются детерминированным экстрактором.

Скрипты

Чтобы перегенерировать вымышленный PDF-документ политики Contoso, установите зависимость скрипта и запустите генератор:

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