prefab-mcp

# prefab-mcp

An MCP server for [Prefab](https://www.prefabapp.io), so an agent can see your templates and
deploy one for you.

    "Set up a new client folder for Northwind, autumn campaign, on my Desktop"

## What it exposes

| Tool | Does |
| --- | --- |
| `list_templates` | Every template, what it creates, what it asks for |
| `describe_template` | One template in full: structure, placeholders, actions |
| `preview_deploy` | What a deploy would create, and what values are still missing. Creates nothing |
| `deploy_template` | Creates the folders, filling in the values given |
| `list_watched_folders` | Folders Prefab is watching, and the rules on them |
| `list_globals` | Library-wide placeholders, actions and value presets |

## Setting it up

Works with any client that speaks MCP over stdio.

**As a bundle** - download `prefab.mcpb` from the
[releases page](https://github.com/davidjaykelly/prefab-mcp/releases) and double-click it. Clients
that install MCP bundles, Claude Desktop among them, bring their own Node, so there is nothing else
to install.

**From the command line** (Claude Code, and anything with the same idea):

    claude mcp add prefab -- npx -y prefab-mcp

**In a config file** - Cursor, Zed, and most others:

```json
{
  "mcpServers": {
    "prefab": { "command": "npx", "args": ["-y", "prefab-mcp"] }
  }
}
```

Then switch on **Let agents and scripts control Prefab** in Prefab's Settings ▸ Permissions. It is
off by default; reading your templates works without it, creating and deploying does not.

That switch arrives in **Prefab 1.1.6**. On an earlier version the reading tools work and the rest
say so.

Requires macOS, Prefab installed and opened once, and Node 18+ (except for the `.mcpb` route).

## How it works

Prefab is sandboxed and has no network access, so it cannot host anything. This server runs beside
it instead: it **reads** the library straight out of the app group
(`~/Library/Group Containers/group.VFDG327T66.prefab`) and **asks the app to deploy** through the
same `prefab://` URL the Finder extension uses. Two consequences worth knowing:

- **Prefab has to be running** for a deploy. Reading works either way.
- **The destination has to be a folder Prefab has been granted.** macOS keeps a sandboxed app out
  of your folders until you point it at one. `preview_deploy` and `deploy_template` both check
  first and say so, rather than leaving a permission dialog on screen that an agent cannot answer.
  Grant folders in Prefab, under Settings ▸ Permissions.

Nothing here writes to Prefab's library. The app owns those files, and editing them behind its
back would be overwritten the next time it saves.

## Development

    npm test    # checks placeholder resolution matches the app's Swift, case for case
    npm run try '[["list_templates",{}]]'    # call a tool the way a client does

`src/resolve.js` is a deliberate duplicate of `RenamePattern.swift`. If you change one, change the
other - `npm test` compiles the Swift and compares the two.