# MCP Server & AI Skill

Two packaged tools make AI-assisted ChainRender development first-class: the **MCP server** (so an AI calls the SDK
as tools) and the **app-builder skill** (so an AI knows the workflow). Both wrap the shipped `@chainrender/client` —
the AI's output stays verifiable (graded, compiled, validated), never blind.

They enforce two things a correct build needs: the **on-chain paradigm** (the component IS the app — compiled,
registered on-chain, rendered by an `eth_call`; not a React app that fetches with viem and hand-renders while
ChainRender only prints a hash — see [Building Correctly](../concepts/building-correctly.md)) and the
**[trust grade](../concepts/trust-grade.md)** (A = fully on-chain/trustless; off-chain dependencies drop the grade
and must be declared, never hidden). The skill teaches both; the MCP `grade` tool proves the second.

## The MCP server — `@chainrender/mcp`

A Model Context Protocol server that exposes the ChainRender SDK as tools, so an AI assistant in an MCP-capable
editor or chat can build apps by calling them directly.

### Tools

| Tool | What it does | Since |
|---|---|---|
| `chainrender_vocabulary` | The closed vocabulary (node types and fields, enums, capabilities, resolver kinds). **Call first.** Optional `include` returns only the named sections (`nodeTypes`, `a11y`, `behavior`, `enums`, `capabilities`, `kinds`, `resolverKinds`, `limits`). | 0.1.0 (`include` 0.4.0) |
| `chainrender_search_kinds` | Find resolver kinds by words (`"uniswap price"`, `"ens"`) and data edge; returns names, one-line summaries and arg names only. | 0.4.0 |
| `chainrender_describe_kind` | One kind's full descriptor: args (name, ABI type, note), `argsEncoding`, data edge, capability, notes. Unknown names return the closest matches. | 0.4.0 |
| `chainrender_check_node` | Check a tree against everything `compile()` reads; reports what it would silently drop, with paths. `authoring: true` accepts builder fields. | 0.4.0 |
| `chainrender_node_schema` | The strict JSON Schema of a tree, to constrain generation. | 0.4.0 |
| `chainrender_grade` | Grade a composition (A/B/C + itemized breakdown); optional `pinnedDep` for Grade B. | 0.1.0 |
| `chainrender_compile` | Compile to the content-addressed hash (deterministic). | 0.1.0 |
| `chainrender_validate` | Enforcer-equivalent checks (pass a manifest `{ name, version, root }`). | 0.1.0 |
| `chainrender_review` | check + grade + compile + (optional) validate in one call — the finalize loop. | 0.1.0 (check 0.4.0) |

**Keep the context small.** The full vocabulary is ~59 KB of JSON, and most of it is the resolver-kind list. An AI
building one component rarely needs every kind: call `chainrender_vocabulary` with every section except
`resolverKinds`, then `chainrender_search_kinds` → `chainrender_describe_kind` for the data sources it actually binds.
Both lookups read the SDK's own `vocabulary()` on every call, so they cannot drift from it.

### Install & configure

```bash
npm install -g @chainrender/mcp   # published — installs the ChainRender MCP server
```

Add to your MCP client's config:

```json
{
  "mcpServers": {
    "chainrender": { "command": "chainrender-mcp" }
  }
}
```

Now the AI can call the tools directly — the same grade/compile/validate loop, without pasting the vocabulary by
hand. The tools are thin wrappers over `@chainrender/client`; no logic is duplicated, so what the tools compute is
exactly what the chain computes.

## The app-builder skill — `chainrender-app-builder`

A **skill** (a `SKILL.md` plus worked examples) that teaches an AI agent *how* to build ChainRender apps well: the
non-negotiable workflow (vocabulary → compose → check → grade → compile → validate), the Grade-A rules, how to encode
resolver args, the toolchain for any Solidity it writes, the do's and don'ts, and request→app examples. Where the MCP server gives the AI the *tools*, the skill gives it the *method*.

Load it wherever your AI tooling discovers skills. It's plain Markdown — no build step. It pairs naturally with the
MCP server: the skill tells the agent the workflow, the MCP tools execute it.

## How they fit together

```
skill (the method)  →  the AI follows the workflow
   +
MCP server (the tools)  →  the AI calls vocabulary / search_kinds / check_node / grade / compile / validate
   +
@chainrender/client (the SDK)  →  the single source of truth both wrap
   =
verifiable AI-built apps: graded, compiled, validated — never blind trust
```

## Docs for agents: `llms.txt`

The docs site publishes itself in the formats coding agents read: **`https://chainrender.org/docs/llms.txt`** (one
line per page: title, Markdown URL, first sentence), **`llms-full.txt`** (every page in one file), and a Markdown copy
of every page (append `.md` to its URL, or use the "Markdown" link in the top bar). Point an agent at `llms.txt`
instead of pasting rules into its prompt.

## Status

- **`@chainrender/client`** — **live on npm** (`npm install @chainrender/client`). `checkNode` / `nodeJsonSchema`
  ship in **0.10.0**; **0.10.1** makes `{ authoring: true }` accept every builder field (`argValues`, `_`-keys).
- **`@chainrender/mcp`** — **published on npm** (`npm install -g @chainrender/mcp`); wraps the SDK's
  `vocabulary`/`checkNode`/`nodeJsonSchema`/`grade`/`compileComponent`/`validateApp`. The kind lookups,
  `chainrender_check_node` and `chainrender_node_schema` ship in **0.4.0**; **0.4.1** depends on client ^0.10.1.
- **`chainrender-app-builder` skill** — built (Markdown; ready to distribute).
- **`create-chainrender`** — **live on npm** (`npm create chainrender@latest my-app`).

## Related
- **[Building with AI](../guides/building-with-ai.md)** — the step-by-step workflow.
- **[Instructing an AI](./instructing-ai.md)** — prompt patterns.
- **[Building Correctly](../concepts/building-correctly.md)** — the on-chain paradigm the skill enforces.
- **[The Vocabulary](./vocabulary.md)** · **[The Trust Grade](../concepts/trust-grade.md)** — the grading the tools compute.