Give your assistant a face

A two-hour, hands-on MCP workshop for final-year students. An assistant calls three local tools; a browser viewer shows the selected reaction immediately.

Status: working application with six clearly labeled development placeholders. The final realistic portrait and expression assets are pending. No LivePortrait, GPU, Python, database, or cloud account is needed to run the student app.

Quick start

Install Node.js 22.12+ (Node 24 recommended) and Git. Clone this repository, then run:

npm ci
npm run build
npm start

Open http://127.0.0.1:3333. Leave the terminal running. In another terminal, run npm run doctor. On PowerShell systems that block npm.ps1, use npm.cmd in place of npm.

Try the buttons, then connect GitHub Copilot or Claude Code. Example prompt: “List the available face expressions, then set the face to shocked.” Approve the tool when asked. The assistant must actually call the tool; ordinary chat text alone does not change the viewer.

Related MCP server: mood

Verify

npm run build
npm test
npx playwright install chromium
npm run test:e2e

npm run verify runs the build, protocol/server tests, and browser tests together. Browser tests use a separate app on port 3344; keep that port free. They spawn a real MCP process over stdio and check browser display acknowledgements. See verification status for the distinction between automated tests and assistant-client rehearsal.

For the complete student lifecycle (fresh starter → implement → browser/MCP tests → backed-up reset → verify starter again), run npm run test:rehearsal or use the workshop-rehearsal skill. See full rehearsal and participant reset instructions. These reusable materials are available on main; use workshop/full-rehearsal for test work.

Teach and learn

• Student exercises and progressive hints

• Instructor plan and pre-work

• Architecture and command status

• Setup and troubleshooting helper

• Assets, attribution, and portrait preparation

The root project is the completed demo. npm run workshop:starter creates a separate workshop-starter/ copy with only list_expressions implemented. It refuses to overwrite an existing copy. The starter builds and runs; the full acceptance tests intentionally fail until the student implements the remaining tools. Solutions stay available for instructor-assisted recovery.

Configuration

The viewer binds only to 127.0.0.1. Default port: 3333. To change it in PowerShell: $env:FACE_PORT='3335', then npm start. Also set FACE_PORT to the same value in the MCP server's env configuration. Never place secrets in the repository. State is in memory: browser refresh restores the current reaction, while restarting the app resets to neutral.

Prepared still images change expressions; this version does not animate speech or lip-sync. Expressions represent conversational reactions, not feelings experienced by an assistant.

Code and original placeholder SVGs: MIT. Any replacement portraits must have their own documented redistribution rights.