Build with MCP

imperal-mcp is a local MCP server that lets your AI client — Claude Code, Cursor, Codex, or any Model Context Protocol host — build, validate, deploy, and read-operate an Imperal app for you. Your client's own model authors the app; the server gives it the rails (the IR spec, the UI catalog, real examples) and the safe verbs (validate, smoke, deploy).

It's the fastest way to go from "I want an app that…" to a deployed Imperal app without hand-writing the SDK — and it's complementary to the SDK path: the app it produces is the same declarative IR the SDK speaks.

Install

pip install imperal-mcp     # or: pipx install imperal-mcp
imperal-mcp login           # opens your browser to authorize — no API key to copy

Then point your MCP client at it. For example, .mcp.json:

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

No token lives in the config — imperal-mcp login handles authorization in your browser and stores the session locally.

What your model gets

When the server is connected, your client's model is armed with:

• Resources — imperal://ir-spec (what an app is), imperal://ui-catalog (every ui.* primitive), and imperal://examples (working apps to learn from).
• A guided prompt — build_imperal_app, which walks the model through authoring a correct app.

Tools

Build

• validate_ir(app_ir) — fully local, no network: checks the IR envelope and every step against the schemas.
• smoke_ir(app_ir, function, args) — runs a function in an isolated sandbox so the model can see real output before deploying.
• deploy_ir(app_ir, app_id) — deploys the app (creates it the first time, updates it on re-deploy).

Operate (read-only, PII-masked)

• list_apps, get_app — discover what's deployed.
• run_read_tool(app_id, function, args) — runs only tools declared action_type: "read"; write/destructive tools are refused, and unknown tools fail closed.

The IR a step speaks

A declarative step is op + args{kind, data} — for example:

{ "id": "s1", "op": "store.create", "args": { "kind": "link", "data": { "url": "…" } } }

The envelope carries ir_version, an app (id + version + title + capabilities), and functions (each with name, action_type, params_schema, return_schema, and a declarative impl.steps). The full vocabulary lives in the SDK Reference.

The flow

1. Arm — your client reads the IR spec + UI catalog + examples.
2. Author — the model writes the app IR.
3. Validate → Smoke — catch shape and behavior issues locally before anything ships.
4. Deploy — deploy_ir publishes it; the app's title and description become its identity across the panel and the Marketplace.
5. Operate — read tools let the model inspect live data (writes always go through the user's own confirmation in the app).

Versions

Release notes live in the project's CHANGELOG.md (GitHub imperalcloud/imperal-mcp):

• 0.3.0 — a deterministic build→deploy door: auto-registers you as a developer, get-or-creates the app, retries only transient errors, and reports truthful results.
• 0.2.0 — browser login (imperal-mcp login).
• 0.1.0 — build · validate · smoke · deploy · read-operate.