Skip to main content
Glama

perch-mcp

The MCP 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:

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

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

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

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

Related MCP server: Hanzo MCP

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

Available Tools

6 tools
perch_docsPerch docsA

The modding and API documentation. Without page, lists pages (id, title, description); with page (e.g. "modding/your-first-widget", "api/host"), returns that page. search finds pages whose text mentions a term.

Inputs: page, search.

perch_examplesPerch builtin packagesA

The builtin Perch packages (media, clock, weather, launcher, …) are complete worked examples of the vocabulary. Without id, lists them; with id, returns every file of that package.

Inputs: id.

perch_guidePerch modding guideA

The short authoring guide for Perch mods: package shape, the Lua declarations (settings/widgets), handlers, scopes, style. Read this first.

Inputs: no named parameters.

perch_runRun a package in PerchA

Launches Perch with PERCH_MOD_DEV pointed at the folder that contains this package, so the widget appears in Settings → Layout → Widgets and on the notch. Windows only. Set PERCH_EXE if Perch is not installed through Steam.

Inputs: package_dir (required).

perch_validateValidate a Perch packageA

Checks a package folder: mod.json against the manifest schema (id = folder name, no legacy widgets/settings keys, known scopes), the entry exists, every .lua parses, the entry declares a widget, and display types exist in the vocabulary. The definitive check is Perch's own loader — run the package (perch_run) and read Settings → Installed mods for the loader's verdict.

Inputs: package_dir (required).

perch_vocabularyPerch display vocabularyA

The canonical vocabulary (api-spec.json): display components and their props, shared props, color roles, host functions, handlers, scopes, contexts. Pass part to fetch one section.

Inputs: part.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool addresses a distinctly different aspect of mod development: learning (guide), reference (vocabulary), documentation (docs), examples (examples), verification (validate), and execution (run). No two tools have overlapping purposes, eliminating ambiguity.

    Naming Consistency5/5

    All tools follow the same lower_snake_case pattern with the 'perch_' prefix, and the second part is a clear noun or verb. The style is uniform, making the toolset predictable and easy to navigate.

    Tool Count5/5

    With six tools, the set is compact and every tool has a clear role in the development workflow. This is within the ideal range and each tool earns its place without redundancy.

    Completeness5/5

    The tools cover the complete mod authoring loop: guidance, API reference, documentation, examples, validation, and runtime testing. No critical gaps are apparent for the stated purpose of developing Perch mods.

    Related MCP Connectors

    Related MCP Servers