# Phonebook [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/stag-build/phonebook  
**GitHub Stars:** 13  
**npm Downloads (last month):** 1462  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/phonebook

## Description
Self-hosted gallery of your SwiftUI #Preview and Jetpack Compose @Preview screens.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "phonebook": {
    "command": "npx",
    "args": ["-y","@stag-build/phonebook"]
  }
}
```

## Documentation

## What Phonebook does

Phonebook creates a Storybook-style gallery from previews already present in an Android or iOS codebase. It collects rendered preview images and metadata into a bundle containing `manifest.json` and an `images/` directory, then converts that bundle into a static HTML site.

The gallery groups previews into component and state cards by interpreting preview names, so teams can review UI variations without adding special annotations. Designers can open the generated site without installing the application or its development toolchain. Each repository is processed independently, and one run targets one platform.

Phonebook is intended for teams that want a local or CI-generated visual catalog, preview coverage checks, and an agent-assisted way to fill gaps in their mobile UI previews.

## How it works

The `generate` command delegates rendering to the platform-specific preview engine. Android uses Roborazzi and ComposablePreviewScanner on the JVM through Robolectric, so generation can run on Linux CI without an emulator. iOS uses SnapshotPreviews through `xcodebuild test` on a simulator, which requires macOS.

The `build` command consumes the generated bundle and creates a plain HTML, CSS, and JavaScript site. By default, `index.html` is placed in the bundle directory and reuses its existing images. Supplying an output directory creates a separate site directory, which can be useful for publishing or combining bundles later. The resulting site can be opened through `file://` or served by a static host.

For Android, `init` detects the project's Kotlin version and resolves compatible setup instructions. `doctor` checks the configuration and can identify Kotlin and Roborazzi metadata mismatches before they appear as compiler failures.

## Setup and configuration

Install the CLI globally with npm or Homebrew, or invoke it without installation through `npx @stag-build/phonebook`. The MCP process runs with `npx -y @stag-build/phonebook mcp` and uses standard input/output, allowing supported coding-agent clients to launch it locally.

Android projects use a `phonebook.config.json` file beside `settings.gradle.kts`. The configuration includes an application name, the `android` platform, the Gradle modules to process, and the build variant. Android setup also requires the Roborazzi, Robolectric, ComposablePreviewScanner, preview-scanner support, and Compose UI test dependencies described by the generated setup instructions.

An Android run can target a repository with `-C /path/to/repository`. The generated files are written under `build/phonebook/`, and the standard output site is available at `phonebook-out/index.html`. iOS projects use SnapshotPreviews and an XCTest target.

## Tools and capabilities

The MCP interface exposes these operations:

- `check_setup` diagnoses project setup in the same role as `phonebook doctor`.
- `analyze_coverage` finds components without previews or dark-mode variants.
- `get_preview_guidance` provides guidance for adding previews.
- `run_generate` renders previews into a Phonebook bundle.
- `run_build` creates the static gallery from that bundle.

Android generation also supports `--changed` and `--files A.kt,B.kt`. These modes limit rendering to previews declared in selected files and use a temporary Gradle init script under the build directory rather than modifying source files. If a project supplies its own preview tester class, that project setting takes precedence and the run renders every preview in the module.

## Limitations and notes

A repository run is single-platform: an Android repository or an iOS repository produces one bundle and one site. Android generation runs without an emulator, while iOS generation needs macOS and a simulator.

Android Studio Gemini Agent Mode cannot connect to Phonebook's local stdio MCP process because its MCP integration currently accepts remote `httpUrl` servers. Claude Code, Codex CLI, Claude Desktop, Cursor, and Xcode agent configurations are documented for local use. Xcode agent support requires Xcode 26.3 or newer.

The generated output is static rather than an application-backed service. Publishing it elsewhere requires hosting the generated files or using the build command's separate output directory.

_Full upstream README: https://allmcps.com/mcp/phonebook/readme_