# perch-mcp

The [MCP](https://modelcontextprotocol.io) server for building **Perch** mods. Point the AI tool you already use at it and it gets what only Perch can give it: the display vocabulary, the docs, the builtin packages as worked examples, a package validator, and a way to run your package in Perch.

Nothing here calls an AI. Your own client (Claude Code, Claude Desktop, Cursor, …) does the thinking on your own account.

## Install

Requires Node 18+.

**Claude Code**

```
claude mcp add perch -- npx -y github:hlpdev/perch-mcp
```

**Claude Desktop** — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "perch": { "command": "npx", "args": ["-y", "github:hlpdev/perch-mcp"] }
  }
}
```

**Cursor** — `.cursor/mcp.json` (project) or the global one:

```json
{
  "mcpServers": {
    "perch": { "command": "npx", "args": ["-y", "github:hlpdev/perch-mcp"] }
  }
}
```

Any other MCP client: run `npx -y github:hlpdev/perch-mcp` over stdio.

## Tools

| Tool | What it gives the model |
| --- | --- |
| `perch_guide` | The short authoring guide: package shape, Lua declarations, handlers, scopes, style. |
| `perch_vocabulary` | The canonical vocabulary (api-spec.json): components and props, color roles, host functions, handlers, scopes, contexts. |
| `perch_docs` | The modding and API docs: list, read a page, or search. |
| `perch_examples` | The builtin packages (media, clock, weather, launcher, …) as complete examples. |
| `perch_validate` | Checks a package folder: manifest schema, entry, Lua syntax, widget declaration, component names. |
| `perch_run` | Launches Perch with `PERCH_MOD_DEV` at your package (Windows; `PERCH_EXE` overrides the Steam lookup). |

Try: *"Make me a Perch widget that shows my Steam friends online, using the perch tools."*

## Updating the bundled content

`content/` is generated from the Perch repos and committed:

```
npm run sync   # needs ../perch, ../perch-studio, ../perch-site checked out
```