Zava Relocation MCP UI 演示

Zava Relocation Inc. 帮助员工因新工作而搬家。本项目是一个参考演示，用于构建一个交互式 MCP App，它使用 MCP-UI、本地 Qwen2.5 7B 模型以及同步的对话式信息收集表单。

用户可以与 Ava 聊天、上传录用通知书，或直接编辑个人资料。提取的信息会立即应用到表单中并高亮显示，以便用户查看发生了什么变化。

如需面向客户的教学演练，请参阅专门的 MCP UI + LLM 表单填写指南。

该演示展示了什么

• 通过聊天驱动表单填写，并实时更新字段

• 可选的浏览器语音模式：与 Ava 对话并听到 Qwen 的语音回复

• 在浏览器中提取 PDF 和 DOCX 录用通知书

• 通过 Foundry Local 使用 Qwen2.5 7B 进行本地解读

• 五个资料部分：联系方式、就业、搬家、搬家物流和偏好

• 基于虚构的 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 在 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. 使用 createUIResource 将生产构建 dist/index.html 加载到 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 或更高版本，以及支持 DirectX 12 的 GPU 用于 Windows ML 运行时。

安装 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 语音开/关 控件启用或禁用语音回复，语音 允许您选择已安装的浏览器语音，停止 Ava 中断当前响应。应用在可用时优先使用 Microsoft/Edge 自然英语语音，例如 Ava、Jenny、Aria 或 Sonia。Chrome 和 Edge 提供最佳支持；需要麦克风权限，语音输入需要 localhost 或 HTTPS。语音质量取决于浏览器安装和暴露的语音。

语音输入使用一次一个字段的引导流程。应用识别下一个未完成的必填字段，要求 Qwen 专注于该字段，在回答后推进活动表单部分，并说出一个简短的下一问题。这使每个语音轮次易于记忆。打字聊天保持自由形式。

文档解析流程

浏览器处理原始文件；文件本身不会上传到云服务：

1. src/App.tsx 验证扩展名和 10 MB 限制。

2. src/documentParser.ts 使用 PDF.js 处理 PDF，使用 Mammoth 处理 DOCX 文件。

3. 提取的文本通过 POST /api/chat 发送到本地 Qwen 进行文档解读。

4. Qwen 返回结构化字段。UI 使用一致的文档审查消息，告知用户审查表单并手动完成任何缺失信息；它不枚举缺失字段。

5. 模型字段被应用并在表单中高亮显示。

有依据的物流演练

上传 contoso-moving-offers-and-reimbursement-guide.pdf，然后向 Ava 提问，例如“对于 250 英里的搬家，哪个选项最好？”或“我可以使用租用的卡车行驶 150 英里吗？”浏览器将提取的政策文本保留为后续聊天轮次的依据，模型被指示仅从该文本回答政策问题。搬家物流部分捕获所选方法、大致距离、报销路径和备注。

浏览器端的 PDF.js 和 Mammoth 库仅是文本提取工具；它们不决定哪些值属于搬家表单。Foundry Local/Qwen 是 PDF/DOCX 字段提取的真相来源。如果模型不可用，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 需要 OCR，PDF.js 才能提取有用的文本。标签值，如 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