Stencil MCP

An MCP server that gives AI coding agents a real-world UI pattern library before they build screens.

Stencil MCP connects AI coding agents — Claude Code, Cursor, Codex — to the Stencil pattern library: a curated collection of structured UI pattern specs derived from real apps. Agents call Stencil tools automatically before building any UI screen, retrieve a relevant reference pattern, and use it to produce output that is visually considered rather than generically trained.

---

How It Works

1. Developer opens a project with Claude Code (or another supported agent)
2. Agent receives a request to build a UI screen — login, onboarding, empty state, settings, etc.
3. Stencil MCP triggers automatically: agent calls search_patterns with the screen type
4. Agent retrieves a structured markdown spec describing a real-world pattern — layout, copy strategy, visual language, design rationale
5. Agent uses the spec as a reference while generating code — adapting the pattern's direction to the project's existing design system

The result is UI that feels like it was designed by someone who studied real apps, not generated by a model defaulting to its training data average.

---

Tools

The server exposes three tools:

search_patterns

Search the pattern library by screen type, style mood, composition, or keyword tag.

ALWAYS call this tool before building any UI screen. Trigger conditions:

• Building or scaffolding a new screen
• Adding a login, signup, or auth flow
• Creating onboarding or welcome screens
• Building empty states or zero-data views
• Adding settings or profile screens
• Implementing any screen a real app would have

search_patterns({
  screen_type: "onboarding", // login | onboarding | empty-state | settings
  style_mood: "minimal", // optional: bold | minimal | warm | playful | rich
  composition: "top-hero", // optional: layout composition filter
  tags: ["carousel", "no-skip"], // optional: tag-based filter
});

Returns a list of matching pattern IDs with summaries.

---

get_pattern

Retrieve the full spec for a specific pattern by ID.

get_pattern({
  id: "onboarding-top-hero-minimal-001",
});

Returns the complete markdown spec including layout structure, element detail, copy patterns, visual language, and design reasoning. Appends agent instructions for how to apply the spec.

---

list_screen_types

List all available screen types and the number of patterns in each.

list_screen_types();

---

Agent Instructions

Every get_pattern response appends the following instructions to the spec:

Agent Instructions: Use this pattern as directional reference. Honor the Visual Language section — particularly visual_inspiration — to orient your aesthetic decisions. Adapt all structural and visual choices to the project's existing design system. Do not override existing design tokens, component libraries, or spacing scales. The goal is output that feels inspired by this pattern, not copied from it.

---

Installation

Prerequisites

• Node.js 18+
• The Stencil pattern library cloned locally

Clone and Build

git clone https://github.com/dayaki/stencil-mcp.git
cd stencil-mcp
npm install
npm run build

Configure Pattern Library Path

In src/index.ts, set the path to your local Stencil patterns directory:

const PATTERNS_DIR = "/absolute/path/to/stencil/patterns";

Rebuild after changing:

npm run build

---

Configuration

Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "stencil": {
      "command": "node",
      "args": ["/absolute/path/to/stencil-mcp/dist/index.js"]
    }
  }
}

Project-Level Auto-Trigger (Recommended)

Add a .claude/settings.json to any project where you want Stencil to trigger automatically:

{
  "systemPrompt": "Before building any UI screen — login, onboarding, empty state, settings, or any screen a real app would have — always call the stencil search_patterns tool first. Use the retrieved pattern spec to inform layout, copy strategy, and visual direction. Adapt the pattern to the project's existing design system."
}

This guarantees the agent queries Stencil without relying solely on the tool description to trigger it.

OpenAI Codex

Add to your Codex MCP configuration:

{
  "mcpServers": {
    "stencil": {
      "command": "node",
      "args": ["/absolute/path/to/stencil-mcp/dist/index.js"]
    }
  }
}

---

Development

Stack

• Runtime: Node.js + TypeScript
• MCP SDK: @modelcontextprotocol/sdk with StdioServerTransport
• Frontmatter parsing: gray-matter
• Pattern source: Markdown files from the Stencil pattern library

Project Structure

stencil-mcp/
├── src/
│   └── index.ts          # server entry point, tool definitions, pattern loader
├── dist/                 # compiled output (gitignored)
├── package.json
├── tsconfig.json
└── README.md

Scripts

npm run build     # compile TypeScript to dist/
npm run dev       # watch mode (if configured)

Adding New Tools

Tools are registered in src/index.ts using the MCP SDK's server.tool() method. When adding a new tool, update the description to be directive — tell the agent when and why to call it, not just what it does. Passive descriptions don't trigger automatically.

---

Pattern Coverage

The Stencil library currently includes 37 pattern specs across 4 screen types:

Screen Type	Patterns	Style Moods Available
login	10	bold, minimal, warm, playful, rich
onboarding	10	bold, minimal, warm, playful, rich
empty-state	9	bold, minimal, warm, playful
settings	8	bold, minimal, warm, rich

---

Philosophy

Intentional direction without override.

Stencil specs guide aesthetic decisions without prescribing pixel values. No hex codes, no exact spacing, no font sizes. The spec tells an agent how a screen should feel and why real apps make certain choices — the agent then adapts that direction to whatever design system the project already has.

The result is UI that has a point of view without fighting the codebase it lives in.

---

Related

• stencil — the pattern library this server indexes

---

License

MIT