# Phonebook

> Phonebook is an open-source MCP server for developer tools. Turns SwiftUI #Preview and Jetpack Compose @Preview screens into a static HTML gallery. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, iOS, Android
- **Website:** https://stag-build.github.io/phonebook/
- **Repository:** https://github.com/stag-build/phonebook
- **MCP Registry name:** io.github.stag-build/phonebook
- **Categories:** developer tools, design and media
- **Listing updated:** 2026-11-15

## About

Phonebook is pitched as a self-hosted, open-source alternative to Emerge Tools Snapshots. Instead of writing new test code, it harvests the previews your team already has and renders them into a Storybook-style gallery that designers can open without installing anything. Cards are grouped as component and state, inferred from preview names with no extra annotation.

The flow has two steps. phonebook generate runs the platform's preview renderer and writes a bundle with a manifest.json and images; on Android it uses Roborazzi and ComposablePreviewScanner on the JVM with no emulator, and on iOS it uses SnapshotPreviews through xcodebuild on a simulator, which needs macOS. phonebook build then makes plain HTML, CSS and JS that works from file:// or any static host. Each repo runs independently and, in version one, handles a single platform.

The MCP server is the recommended way in: a coding agent can check setup, analyse preview coverage, add missing previews and build the gallery. Init and doctor commands resolve library versions against the project's Kotlin version to catch metadata mismatches early.

## Features

- **Reuses existing previews:** Harvests @Preview and #Preview code with no new test code.
- **Static HTML gallery:** Output works from file:// or any static host, with no SaaS account.
- **Agent-driven setup:** The MCP server lets an agent check setup, find missing previews and build the site.
- **Component and state cards:** Groups previews by names without needing annotations.
- **Android on the JVM:** Roborazzi and Robolectric render previews without an emulator.
- **Version-aware init:** init and doctor align library versions with the project's Kotlin version.

## Good for

- Publish a component gallery for designers from an Android repo
- Review iOS SwiftUI preview states without opening Xcode
- Find components that lack previews
- Generate the gallery in CI
- Let a coding agent set up preview rendering

## Install

### Claude Code (Terminal)

```sh
claude mcp add phonebook -- npx -y @stag-build/phonebook
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## FAQ

### Do I need a SaaS account?

No. It is self-hosted and runs locally or in your CI.

### Can one repo cover both platforms?

Not in v1; one Android or iOS repo produces one bundle and one site.

### What does iOS need?

macOS, since previews render with xcodebuild on a simulator.

### How do I start the MCP server?

Run npx -y @stag-build/phonebook mcp, for example via claude mcp add phonebook.

### How can I install the CLI?

npm install -g @stag-build/phonebook or Homebrew.

### Is Phonebook free?

Yes. Phonebook is open source, so you can use and self-host it for free.

### How do I add Phonebook to Claude Code?

Run this command in your terminal: claude mcp add phonebook -- npx -y @stag-build/phonebook

### What are the best alternatives to Phonebook?

The closest alternatives to Phonebook are REA, HyperFrames by HeyGen, Codebase Memory, GitHub and Serena MCP: the IDE for your agent.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/phonebook
