Zava Relocation MCP UI Demo

Zava Relocation Inc. ayuda a los empleados a mudarse por un nuevo trabajo. Este proyecto es una demo de referencia para construir una MCP App interactiva con MCP-UI, un modelo local Qwen2.5 7B y un formulario de registro conversacional sincronizado.

El usuario puede chatear con Ava, subir una carta de oferta o editar el perfil directamente. La información extraída se aplica al formulario de inmediato y se resalta para que el usuario pueda revisar lo que ha cambiado.

Para un tutorial didáctico orientado al cliente, consulta la guía de relleno de formularios con MCP UI + LLM.

Qué demuestra la demo

• Completado del formulario mediante chat con actualizaciones de campos en vivo

• Modo de voz opcional en el navegador: habla con Ava y escucha las respuestas de Qwen en voz alta

• Extracción de cartas de oferta en PDF y DOCX en el navegador

• Interpretación local con Qwen2.5 7B a través de Foundry Local

• Cinco secciones de perfil: contacto, empleo, mudanza, logística de mudanza y preferencias

• Orientación fundamentada sobre opciones de mudanza y reembolsos a partir del PDF ficticio de la política de Contoso

• Seguimiento del progreso, actualizaciones de IA resaltadas, reinicio y estado de finalización

• Diseños adaptables para escritorio y móvil

• Vinculación de recursos/herramientas de MCP Apps mediante @mcp-ui/server y @modelcontextprotocol/ext-apps

• Una compilación de producción que integra la interfaz en un único recurso HTML

Límite de la demo: Este es un prototipo local. No persiste casos de reubicación, no autentica usuarios ni envía datos a un sistema de recursos humanos de producción. Los PDF de ejemplo en sample-documents/ contienen datos ficticios.

Related MCP server: Docalyze

Arquitectura

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

Hay dos formas de usar la interfaz:

1. Modo independiente: Vite sirve la aplicación React en http://localhost:5173.

2. Modo MCP App: Un host compatible con MCP Apps se conecta a http://localhost:3001/mcp, descubre start_relocation_intake y renderiza el recurso vinculado ui://zava-relocation/intake.

Cómo se aprovecha MCP-UI

Este proyecto utiliza el patrón MCP Apps recomendado por MCP-UI:

1. server/index.ts crea un McpServer y un StreamableHTTPServerTransport.

2. El dist/index.html de producción se carga en un recurso de interfaz mediante createUIResource.

3. registerAppResource publica ese recurso en ui://zava-relocation/intake.

4. registerAppTool expone start_relocation_intake y lo vincula a la interfaz con:

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

5. La interfaz integrada indica que está lista con ui-lifecycle-iframe-ready y puede enviar mensajes al host con window.parent.postMessage.

La distinción importante es que el servidor MCP no renderiza el formulario en sí. Registra la herramienta y el recurso de interfaz; el host de MCP Apps decide dónde y cómo mostrar ese recurso.

Foundry Local y Qwen2.5 7B

El asistente utiliza Qwen2.5 7B a través de Foundry Local. Foundry Local se ejecuta en la misma máquina que este servidor Node y expone un endpoint local de chat-completions compatible con OpenAI. No se ha configurado ningún modelo en la nube de respaldo.

Requisitos previos

El soporte de Foundry Local depende de la máquina host. En Windows, Microsoft documenta Windows 11 24H2 o posterior, .NET 9 o posterior y una GPU compatible con DirectX 12 para el runtime de Windows ML.

Instala la CLI de Foundry Local:

winget install Microsoft.FoundryLocal

Cierra y vuelve a abrir PowerShell y, a continuación, verifica la CLI:

foundry --version

Enumera los alias de modelo disponibles en el catálogo local:

foundry model list

Inicia o descarga el modelo Qwen usando el alias que muestra el catálogo. El alias esperado para la demo es:

foundry model run qwen2.5-7b

Mantén Foundry Local en ejecución mientras usas la demo. El endpoint actual del servicio Foundry Local para este proyecto es:

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

Si el catálogo instalado usa un alias o puerto diferente, configura el servidor Node antes de iniciarlo:

$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 asigna el puerto del servicio dinámicamente. Usa foundry service status o foundry service list para inspeccionar el servicio activo, y usa GET http://127.0.0.1:<port>/openai/models para enumerar los ID de modelo disponibles. El ID de modelo exacto puede variar según el hardware; en esta máquina, el modelo Qwen GPU disponible es qwen2.5-7b-instruct-cuda-gpu.

Qué recibe el modelo

server/foundryLocal.ts envía a Qwen:

• El último mensaje del usuario o una instrucción de revisión de documento

• El estado actual del formulario

• Hasta 8.000 caracteres de texto extraído del documento

El prompt del sistema le pide a Qwen que devuelva JSON con esta forma:

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

El servidor solo acepta claves de formulario incluidas en la lista blanca. El modelo no puede añadir campos arbitrarios al estado del cliente.

Modo de voz

Qwen2.5 7B sigue siendo un modelo solo de texto. El modo de voz utiliza las capacidades del navegador en torno al pipeline de texto existente:

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

Haz clic en el botón de micrófono del compositor para hablar. Cuando termina el reconocimiento, la transcripción se envía a través del mismo flujo de chat que usan los mensajes escritos. El control Ava voice on/off activa o desactiva las respuestas habladas, Voice te permite elegir una voz instalada en el navegador y Stop Ava interrumpe la respuesta actual. La aplicación prefiere las voces naturales en inglés de Microsoft/Edge cuando están disponibles, como Ava, Jenny, Aria o Sonia. Chrome y Edge ofrecen el mejor soporte; se requiere permiso de micrófono y la entrada de voz necesita localhost o HTTPS. La calidad de la voz depende de las voces instaladas y expuestas por el navegador.

La entrada de voz utiliza un flujo guiado de un campo a la vez. La aplicación identifica el siguiente campo obligatorio incompleto, le pide a Qwen que se centre en ese campo, avanza la sección activa del formulario después de la respuesta y dice una pregunta breve a continuación. Esto hace que cada turno de voz sea fácil de recordar. El chat escrito sigue siendo de formato libre.

Flujo de análisis de documentos

El navegador gestiona el archivo original; el archivo en sí no se sube a ningún servicio en la nube:

1. src/App.tsx valida la extensión y el límite de 10 MB.

2. src/documentParser.ts usa PDF.js para PDF y Mammoth para archivos DOCX.

3. El texto extraído se envía a Qwen local mediante POST /api/chat para la interpretación del documento.

4. Qwen devuelve campos estructurados. La interfaz usa un mensaje de revisión de documento coherente que le indica al usuario que revise el formulario y complete manualmente cualquier información faltante; no enumera los campos que faltan.

5. Los campos del modelo se aplican y se resaltan en el formulario.

Recorrido guiado de logística fundamentada

Sube contoso-moving-offers-and-reimbursement-guide.pdf y luego hazle preguntas a Ava como «¿Qué opción es mejor para una mudanza de 250 millas?» o «¿Puedo usar un camión alquilado para 150 millas?». El navegador conserva el texto extraído de la política como base para los turnos de chat posteriores, y se le indica al modelo que responda a las preguntas sobre la política solo a partir de ese texto. La sección Logística de mudanza captura el método seleccionado, la distancia aproximada, la vía de reembolso y las notas.

Las librerías PDF.js y Mammoth del lado del navegador son solo utilidades de extracción de texto; no deciden qué valores pertenecen al formulario de reubicación. Foundry Local/Qwen es la fuente de verdad para la extracción de campos en PDF/DOCX. Si el modelo no está disponible, la interfaz informa del error en lugar de rellenar silenciosamente los campos del documento con un analizador que no es LLM.

Referencias de código

Instalación y ejecución

Instala las dependencias de Node:

npm install

Modo de desarrollo independiente

Inicia Vite y el servidor MCP juntos:

npm run dev

Abre:

http://localhost:5173

El proxy /api de Vite reenvía las solicitudes del modelo local al puerto 3001.

Modo MCP Apps

Compila primero la interfaz. El servidor MCP integra el dist/index.html resultante:

npm run build
npm start

Configura el host compatible con MCP Apps con:

http://localhost:3001/mcp

Luego llama:

start_relocation_intake

El servidor también expone una comprobación de salud básica:

http://localhost:3001/health

Flujo de trabajo de la demo

1. Inicia Foundry Local y asegúrate de que el modelo Qwen esté disponible.

2. Ejecuta npm run dev.

3. Haz clic en una indicación rápida o escribe un mensaje de reubicación.

4. Observa cómo los campos coincidentes se rellenan y se resaltan.

5. Sube uno de los PDF de sample-documents/.

6. Revisa los campos extraídos y enriquecidos por el modelo.

7. Usa Reset demo para volver al estado en blanco.

Indicaciones de chat útiles:

• 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.

Solución de problemas

Could not connect to Foundry Local

Comprueba que Foundry Local esté en ejecución, que el modelo se haya descargado/cargado y que el endpoint coincida con FOUNDRY_LOCAL_ENDPOINT.

Model not found

Ejecuta foundry model list y establece FOUNDRY_LOCAL_MODEL en un alias del catálogo instalado.

El servidor MCP dice Missing dist/index.html

Ejecuta:

npm run build

antes de npm start.

El formulario no encuentra campos en un documento

El PDF debe contener texto seleccionable. Los PDF escaneados o solo de imagen necesitan OCR antes de que PDF.js pueda extraer texto útil. Los valores etiquetados como Employee name:, Email address:, New employer:, Job title:, Start date:, Moving from: y Moving to: son los más fáciles de reconocer para el extractor determinista.

Scripts

Para regenerar el PDF de la política ficticia de Contoso, instala la dependencia del script y ejecuta el generador:

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