Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Formula Book pull up Priya Shah's last formula and scale it one and a half times"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Formula Book lets hair colourists say a client's colour formula at the bowl and get it back, scaled, next visit.
It is a self-hosted MCP server (Streamable HTTP, MCP spec 2025-11-25) with three tools and an MCP Apps formula card. The demo drives it from a simulated Alexa+ client in this repo, labelled on every screen. It has not been tested on a real Alexa+ device.
Try it without installing: https://formula-book-eight.vercel.app/sim runs the real Formula Book and salon diary server code inside your browser tab (badge: "Server in this tab"), over in-memory MCP transports instead of Streamable HTTP, because the host has no long-running process to keep MCP sessions on. Same tools, card, elicitation and free-plan cap; saves last until you reload. Pick "Claude Haiku 5.5" in the Chooser to try "Who's booked in today? Get their bowls ready" (Claude runs on the server, capped at 400 calls a day). For Streamable HTTP, run it locally ("Run it" below).
Prior art | What it does | What Formula Book adds |
Kenra Color skill for Alexa (2019) | Brand questions by voice: colour conversions, mixing instructions, processing times for the top 25 shades | Per-client memory, scaling to today's bowl, refusing an unknown client, a card on screen devices |
Daviana ColorLab | Weighs the bowl on a Bluetooth scale, suggests a formula from a photo, reloads a client's last formula, confirms rather than guesses | Voice capture and spoken scaling at the bowl, on any scale, no extra hardware |
Salon software (Zenoti, Phorest, Goldie, SureTint) | Stores formulas per client | Capture at the bowl by voice. They could add a microphone button; our answer is speed, one job, and an MCP surface any assistant can call |
Kenra's skill answers brand questions: conversions, ratios, times. Salon software and Daviana already keep each client's formula, and Daviana weighs the bowl with its own scale. Formula Book does it by voice at the bowl: say the grams, ask for one and a half times, hear it back. Any scale, no extra hardware.
Related work: alexa-plus-sim, an Echo-Show-style simulator with a Bedrock tool loop, elicitation and MCP Apps. None of its code is used here. Our simulator is small and exists because the rules need the simulation's source in the repo.
Related MCP server: HouseLedger
Part | Status |
MCP server, Streamable HTTP, spec 2025-11-25; also accepts 2025-03-26 | Real |
Three tools: | Real |
Two clients with one name: the server asks through MCP elicitation; on 2025-03-26, or a client without the | Real |
MCP Apps card: | Real, in our own host |
| Our guess. The official list is partner-only. The card falls back to |
Alexa+ itself | Simulated. A web page acting as the host: it lists tools, picks one, calls it over MCP and shows the card |
Choosing the tool | Two choosers, and the badge always names the one that ran. Default: a rule parser ( |
Voice in | Chrome's Web Speech API. Chrome may send the audio to its vendor's speech service. Accuracy on shade codes is not measured; the text box always works |
Voice out | The browser's |
Second MCP server: the salon diary ( | Real server, demo appointments. With the Claude chooser, "Who's booked in today? Get their bowls ready" reads the diary, then gets each booked client's formula from Formula Book, then Claude says one closing sentence: a loop of up to three rounds, each result fed back to Claude ( |
Several clients in one sentence | With Claude: up to three calls per round, run in order, all or nothing ( |
Free plan of 50 formulas | Real: the server refuses the 51st save |
Price | "Hypothesis, payments not live". Nobody is charged |
Waitlist | A local JSON file ("Local demo store") in |
Demo data | Seeded, labelled "Demo data" in the app. Lena, Priya Shah, Priya Kapoor and Booth 12 are not real people |
flowchart LR
subgraph Host["Simulated Alexa+ host (apps/web, labelled on screen)"]
MIC["Mic: Web Speech"] --> CH{"Chooser"}
TXT["Text box"] --> CH
CH -->|default| RP["Rule parser"]
CH -->|optional| CL["Claude Haiku 5.5 via /api/choose"]
RP --> MC["MCP client"]
CL --> MC
MC --> FR["Sandboxed iframe + AppBridge"]
MC --> TTS["speechSynthesis"]
end
subgraph Server["Formula Book MCP server (apps/mcp-server)"]
T1["get_last_formula"]
T2["scale_formula"]
T3["save_formula"]
CARD["ui://formula-card resource"]
CORE["formula-core maths"]
STORE[("Per-salon store")]
end
MC <-->|"Streamable HTTP, JSON-RPC, 2025-11-25"| Server
Server -.->|"elicitation/create: which Priya?"| MC
T1 --> CORE
T2 --> CORE
T3 --> STOREOne turn: the utterance goes to a chooser, which picks a tool from the server's own tools/list. The host sends tools/call with the salon's bearer token. The server resolves the client (asking through elicitation if two match), does the maths, checks the plan cap and returns structuredContent, a speakable sentence and _meta.ui.resourceUri. The host renders the card it prefetched, or on the speaker frame speaks the sentence. Every JSON-RPC message appears in the traffic panel.
Criterion | Evidence in this repo |
Tech implementation | MCP server on spec 2025-11-25 over Streamable HTTP with per-session state ( |
Design | One golden path for one user at the bowl; loading, empty, refusal and error states; three device frames from one result; every refusal is plain words with a next step, no codes |
Potential impact | A named user (independent colourists, about 48% of 575,200 US hairdressers are self-employed); comparables that already charge for formula records ( |
Quality of the idea | Voice capture and spoken scaling at the bowl, on any scale; the same server serves a screen card, a phone card and a speaker sentence; the server asks rather than guesses |
Product feedback |
|
Node 22 or later, Chrome.
npm install
npm run dev:allOpen http://localhost:3000/sim for the simulated Alexa+ demo, or http://localhost:3000/site/index.html for the product site (static HTML, CSS and GSAP in apps/web/public/site). Try "Lena's last formula", then "Make it one and a half times", then "Colour Marta: 30 grams 6N and 20 grams 7.1, 20 volume, one to one and a half".
dev:all also starts the salon diary MCP server at http://127.0.0.1:8790/mcp (stateless, demo data); the sim connects to both and shows "+ Salon diary server". The MCP endpoint is http://127.0.0.1:8787/mcp. Two public demo tokens guard demo data only: demo-salon-token and booth12-token (send Authorization: Bearer <token>). Set SALON_TOKENS for your own.
Variable | Default | Meaning |
| 8787 | Server port |
|
| Endpoint path |
|
| Where salons and the waitlist are stored |
| the two demo tokens |
|
| 50 | Formulas per salon on the free plan |
| off |
|
| off |
|
| unset | Web app only. Enables the Claude chooser. Read on the server, never sent to the browser. About 700 input tokens per choice; 30 calls a minute at most |
| on when a key is set |
|
| 8790 | Diary server port ( |
| unset | Web app only. |
| 400 | Web app only. Claude chooser calls per UTC day per server instance |
apps/mcp-server/src/in-tab.ts builds the same Formula Book server (buildServer) and the diary server and connects them to the sim over InMemoryTransport pairs, with a MemoryStore seeded from seed/. Only the transport differs from the HTTP servers. The card HTML is generated into src/card-html.ts by npm run build:card -w @formula-book/mcp-server, so the server code needs no file access; a test fails if it is stale.
Replay answers without any server code at all. apps/web/lib/replay-transport.ts stands in for the Streamable HTTP transport: the real MCP SDK client sends its JSON-RPC to it and gets back the real server's replies, recorded by apps/web/scripts/record-replay.ts into apps/web/lib/replay-fixture.json. Initialize, tools/list, the card resource and the elicitation round trip for the two Priyas all go through the normal host code, and show in the traffic panel. A save is remembered for the rest of the tab, across new sessions. Anything outside the recorded sentences gets a plain refusal saying so, never a guessed formula. The banner reads "Recorded MCP server replies" and the badge "Replay". Open /sim?replay=1 locally to try it, or press "Switch to replay" when the server is not reachable. To re-record: start the server with DEMO_ADMIN=1, then MCP_URL=http://127.0.0.1:8787/mcp npx tsx apps/web/scripts/record-replay.ts.
npm testnpm run typechecknpm run e2enpm run e2e:x10Unit and server tests run with Vitest (about 93% of lines). The Playwright golden path runs ten steps in Chrome against the real server, with every card assertion made inside the MCP Apps iframe, and e2e:x10 runs it ten times in a row.
packages/formula-core: formula maths, client-name matching, speech normalising, the spoken sentence.
apps/mcp-server: the MCP server, its tools, the card (card/), store, plan and waitlist routes.
apps/web: the simulated Alexa+ host at /sim.
e2e: Playwright tests. seed: demo data. docs: friction log, product feedback, validation questions.
video: the script that recorded the demo video. record.mjs drives real Chrome through the golden path against a running server and captures frames with Chrome's screencast; mux.mjs lays the narration over them with ffmpeg. The narration is synthesised speech (edge-tts), and the footage is the product running, not a mock-up.
During the hackathon: modelcontextprotocol/ext-apps#824, a README note saying which ext-apps line to use with the v1 MCP SDK (1.x peers on @modelcontextprotocol/sdk, 2.x on the split v2 packages). This project hit that question while choosing versions.
Others already sell formula records: SalonScale says over 8,000 salons use it to weigh and save formulas, Vish and Daviana charge salons monthly for per-client formula history, and App Store apps such as Charm and Gloss sell formula saving to independent stylists. That shows the job is paid for; it does not show demand for doing it by voice. Sources and limits are in docs/market-evidence.md.
Pricing hypothesis: free for the first 50 formulas, then a paid plan per colourist. The price has not been tested with anyone. No colourist conversations have happened yet; the three questions we would ask are in docs/validation.md. The builder has no salon contacts.
TypeScript, @modelcontextprotocol/sdk 1.32.1, @modelcontextprotocol/ext-apps 1.7.5, Express 5, Next.js 16, React 19, Tailwind 4, Vitest, Playwright. AI tools: Claude Code wrote most of the code under the builder's direction; an Anthropic API pipeline did the research and spec. See docs/product-feedback.md and docs/friction-log.md.
MIT. See LICENSE.
This server cannot be deployed
Voice notes that organize themselves. Capture by Siri, AI auto-tags, semantic search retrieves.
AI note taker for phone calls, meetings and in-person talks. Search, quote, act on recordings.
Household-aware cooking brain: pantry, meal suggestions, dietary safety, recipes, shopping lists.
Pronunciation scoring, speech-to-text, and text-to-speech for language learning