Skip to main content
Glama
mcp-face-workshop

mcp-face-workshop

by ridamansour

Xperience · Give your assistant a face

About this project

Give Your AI Assistant a Face: MCP Workshop · Xperience, led by Rami Younes (RamiY123) of GE HealthCare · EasTech (Nov 2026)

Hands-on workshop on building AI agent tools with the Model Context Protocol (MCP) in TypeScript and Node.js. I connected Claude Code and GitHub Copilot to an MCP server and wrote the tools that let the assistant change an animated face in a live browser viewer, choosing from 12 expressions. The work included checking tool inputs with Zod schemas, returning a clear error when the app is unreachable, adding an optional timed reset back to a neutral face, and running Playwright tests from the assistant through to the browser.

My implementation: exercises/student-tools.ts (set_expression, reset_expression) and exercises/participant/timed-reset.ts (timed return to neutral).

Tech: TypeScript · Node.js · Model Context Protocol (MCP) · Zod · Express · Playwright


main is the official participant starter. Clone it and work directly in the repository. Create your assistant connection, implement expression tools, and see the results in the prepared browser viewer.

Related MCP server: agent-vrm-mcp

Prepare

Install Node.js 22.12+ (Node 24 recommended), Git, and your chosen client: VS Code with Copilot or Claude Code. Sign in and check account/tool access. Connecting MCP is the first exercise, not a prerequisite.

git clone --branch main --single-branch --depth 1 https://github.com/RamiY123/mcp-face-workshop.git
cd mcp-face-workshop
npm ci
npm run build
npm start

Open http://127.0.0.1:3333 and try the manual buttons. Leave that terminal running; use another for npm run doctor. On PowerShell, use npm.cmd if npm.ps1 is blocked. No database, Docker, GPU, or Python runtime is required.

Start the lab

Read the exercises. Client configurations are deliberately absent. list_expressions is the working example; implement set_expression and reset_expression in exercises/student-tools.ts. There is no completed solution directory or hidden solution mode on this branch.

Agent instructions prohibit copying answers from presenter branches, Git history, remotes, or other checkouts. Ask for hints and explanations based on your own work. The instructor keeps a separate complete demo; it is not the participant starting point.

Check progress

npx playwright install chromium
npm run verify

Baseline verification passes before the exercises: prepared viewer, listing, HTTP behavior, and reset safety. After writing your configuration, run npm run check:connection -- copilot (or claude). After implementing both tools, run npm run test:acceptance for complete MCP-to-browser checks. Acceptance tests intentionally fail before implementation.

npm run check:starter is a distribution/CI check for untouched starters. It is expected to fail after creating configuration or editing the exercise; it is not a student progress grade.

Reset

Preview with npm run workshop:reset, then add -- --apply to restore the initial tool exercise with backups. To also repeat the connection exercise, preview npm run workshop:reset -- --include-client-config, then add --apply. Unrelated client entries are preserved. Rebuild and restart MCP afterward. See the reset guide for exact scope.

Default port: 3333. If changing it, set FACE_PORT consistently in the app and MCP environment. State survives browser refresh; app restart resets to neutral.

The 12 images are expressive illustrated demo assets, including angry, happy, laughing, sad, sleepy, and love. Final realistic portraits and personal-face uploads remain future work. Expressions represent selected reactions, not experienced feelings. Code and original SVGs are MIT; the Xperience logo remains its owner's brand asset (see web/public/branding/README.md).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers