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를 단일 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를 사용하는 방법은 두 가지입니다:

1. 독립 실행 모드: Vite가 React 애플리케이션을 http://localhost:5173에서 서빙합니다.

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 호환 로컬 chat-completions 엔드포인트를 제공합니다. 클라우드 모델 폴백은 구성되어 있지 않습니다.

사전 요구 사항

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를 사용하고, 사용 가능한 모델 ID를 나열하려면 GET http://127.0.0.1:<port>/openai/models를 사용하세요. 정확한 모델 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 음성 켜기/끄기 컨트롤은 음성 응답을 활성화/비활성화하고, 음성은 설치된 브라우저 음성을 선택할 수 있게 하며, Ava 중지는 현재 응답을 중단합니다. 앱은 사용 가능한 경우 Ava, Jenny, Aria, Sonia 같은 Microsoft/Edge 자연스러운 영어 음성을 선호합니다. Chrome과 Edge가 가장 잘 지원하며, 마이크 권한이 필요하고 음성 입력에는 localhost 또는 HTTPS가 필요합니다. 음성 품질은 브라우저에 설치되어 노출되는 음성에 따라 달라집니다.

음성 입력은 한 번에 한 필드씩 안내하는 흐름을 사용합니다. 앱은 다음으로 완료되지 않은 필수 필드를 식별하고, Qwen이 해당 필드에 집중하도록 요청하며, 답변 후 활성 양식 섹션을 진행하고 다음 질문을 짧게 하나 말합니다. 이렇게 하면 각 음성 턴을 기억하기 쉽습니다. 입력된 채팅은 자유 형식으로 유지됩니다.

문서 파싱 흐름

브라우저가 원본 파일을 처리합니다. 파일 자체는 클라우드 서비스에 업로드되지 않습니다:

1. src/App.tsx가 확장자와 10MB 제한을 검증합니다.

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마일 이사에 렌트 트럭을 사용할 수 있나요?” 같은 질문을 해 보세요. 브라우저는 추출된 정책 텍스트를 이후 채팅 턴의 근거 자료로 유지하며, 모델은 정책 질문에 해당 텍스트에서만 답하도록 지시받습니다. 이사 물류 섹션은 선택한 방법, 대략적인 거리, 비용 상환 경로, 메모를 저장합니다.

브라우저 측 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 중 하나를 업로드합니다.

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