Phonebook — Claude Code MCP server: a gallery of SwiftUI and Compose previews
Harvests the @Preview and #Preview declarations already in your Android or iOS repo and builds a static HTML gallery of screens. Useful when a designer needs to see the UI without building the app.
claude mcp add phonebook -- npx -y @stag-build/phonebookWhat Phonebook does
Phonebook does not ask you for new test code. It reuses the previews you wrote and renders them into cards grouped as component and state, with the grouping inferred from the preview names. The MCP server is the entry point: an agent can diagnose the setup, list components that lack a preview or a dark variant, run the render, and build the site.
Rendering differs per platform. On Android, Roborazzi and ComposablePreviewScanner run on the JVM, so a Linux CI job works without an emulator. On iOS, SnapshotPreviews goes through xcodebuild test on a simulator, which means macOS.
Output is a bundle holding manifest.json and an images/ folder. By default phonebook build writes index.html into that same folder, reusing the images in place; passing -o copies everything into a separate site directory instead.
A repo maps to a single site. v1 handles one platform at a time, so an Android bundle and an iOS bundle stay apart. Android Studio's Gemini Agent Mode cannot host it: that integration only takes remote servers over httpUrl, while Phonebook runs as a local stdio process. Drive it from Claude or Codex CLI inside the Android repo.
What it helps with
- turn existing previews into a browsable component gallery
- give designers a link to every screen state without an app build
- spot components that never got a preview or a dark variant
- catch Kotlin and Roborazzi metadata mismatches before compilation fails
- produce a static site that opens from a local folder
Example prompts for the agent
- Use the phonebook MCP and create a catalog for my designer
- Check with phonebook which components are missing previews and add them
- Generate a bundle, then build a standalone site directory from it
How to install Phonebook
Platform CLI
claude mcp add phonebook -- npx -y @stag-build/phonebookPlatform CLI
codex mcp add phonebook -- npx -y @stag-build/phonebookConfig file
{
"mcpServers": {
"phonebook": {
"command": "npx",
"args": [
"-y",
"@stag-build/phonebook"
]
}
}
}Config file
{
"servers": {
"phonebook": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@stag-build/phonebook"
]
}
}
}Platform CLI
gemini mcp add phonebook npx -y @stag-build/phonebookStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Phonebook
How do I install Phonebook in Claude Code?
Run claude mcp add phonebook -- npx -y @stag-build/phonebook. The server starts through npx, so there is nothing to install beforehand.
What does Phonebook do?
It renders your Compose and SwiftUI previews into a static HTML site grouped by component and state. The agent also gets tools for setup checks, preview coverage, generation and build.
Does it need an emulator or a Mac?
Android rendering happens on the JVM, so no emulator is involved. iOS runs through a simulator with xcodebuild test, which requires macOS.
