kasy-mcp

An MCP server for the Kasy kit. It runs locally on your machine — installed for free via npm/npx, no server hosted by Kasy involved — and exposes the kasy CLI (already a dependency of this package, nothing else to install) as tools any MCP-capable AI can call: Claude Desktop, Claude Code, Cursor, and anything else that speaks MCP.

It also exposes this project's own design-system guide as an MCP resource, so the AI reads this project's real components/tokens/docs before building a screen, instead of guessing or inventing raw Material widgets.

What it adds over just running kasy in a terminal

Nothing, technically — every tool here shells out to the same kasy command you'd run yourself, including its license check. The point is for people who don't have (or don't want) a terminal: ask "prepare my machine with Kasy" or "create a project with Kasy" in a chat, and the AI does it through this MCP instead of walking you through commands to copy-paste.

Install

Stable (recommended):

npm install -g kasy-mcp

{
  "mcpServers": {
    "kasy": {
      "command": "kasy-mcp"
    }
  }
}

Quick start with npx (fine for a first try; if MCP turns red after an update, run kasy doctor --heal-mcp or switch to the global install above):

claude mcp add kasy -- npx -y kasy-mcp

{
  "mcpServers": {
    "kasy": {
      "command": "npx",
      "args": ["-y", "kasy-mcp"]
    }
  }
}

Tools (overview)

run_app asks (via the assistant) which platform, and for web whether to open Flutter Chrome or only print http://localhost:5555. Do not use run_kasy_command for kasy run.

The configure_* tools replace the interactive wizards (kasy ios/android/ codemagic configure, full kasy configure), which can't run over MCP because stdin is closed: the assistant collects every value via structured quiz UI or MCP elicitation first, then calls the tool once with all of them.

Licensed playbooks (where the long instructions live)

rebrand_project, create_screens and finalize_project do not carry their instructions in code. They ask the kasy-playbook edge function, which returns the Markdown only for an active subscription on this machine. No public page and no copy inside the npm package. Without a key, with an inactive plan, on another device, or offline, the tool returns PLAYBOOK LOCKED.

Ship an instruction change:

# 1. edit mcp/playbooks/<name>.md
node mcp/scripts/sync-playbooks.js
node mcp/test/playbooks.test.js
# 2. deploy the function (not the marketing site):
supabase functions deploy kasy-playbook --project-ref xkefozfsrmqjtesiitvk

create_screens builds immediately for one screen. A whole product goes through finalize_project, which returns one stage at a time and records it under ~/.kasy/flow-runs/. create_project and create_screens refuse until that tool returns the build stage, after the summary yes and the plan yes (the plan yes includes whether there is a reference, and the pushed routes). With no reference, the kit welcome, login, sign up, home and settings stay. With a reference, every product screen is rebuilt in that look (welcome, login, sign up, profile, settings presentation, menu). Paywall and admin stay the kit. The plan yes also takes referenceImages (a path forces the reference on, even with a short brief) and checks (a tap the tool will perform). Before verify, the assistant looks at every screen again (fidelity, the action, the destination) and says which screen it is on, instead of going quiet. Verify drives the running web app itself, in light and dark, phone and wide, compares the screen color to the image, performs those taps, and runs flutter analyze. .kasy/screen-audit.json does not pass. Verify also stays while a product screen is still the kit file or uses ListTile. Tests run in the editor browser beside the chat, one screen at a time. Talk to the person about the screen that is open, in plain language, in the language of the conversation. Do not say it will be ready in a few minutes. rebrand_project still applies only with confirmed: true.

Structured user questions (quiz UI)

When a tool needs several choices (create project, run platform, configure wizards), agents should not paste numbered markdown lists in chat.

1. IDE quiz (Cursor): use AskQuestion step by step, then call the tool with all args. Do not set useElicitationForm in Cursor. The Cursor MCP elicitation renderer does not turn enum into dropdowns and may pre-fill the first enum value, so the form is not a substitute for AskQuestion.
2. MCP elicitation: for clients without quiz UI (Claude Desktop, etc.), call the tool with useElicitationForm: true and missing required args. Choice fields use a blank first enum value so clients that auto-fill enum[0] do not pick a real default.
3. Fallback: one short open question only when neither exists.

Resources

Local development

npm install
node scripts/smoke-test.js