How It Works

When you run pulse in a project directory, a Model Context Protocol (MCP) server starts alongside the dev server. That MCP server is what gives your AI agent the knowledge, tools, and guardrails to build Pulse pages correctly — without you having to explain the framework in every prompt.

The Pulse MCP server

MCP is a standard protocol that connects AI agents to external tools and knowledge. When Claude (or any MCP-compatible agent) opens a Pulse project, the MCP server is automatically detected and two things happen:

The agent gains access to resources — read-only documents it can fetch at any time
The agent gains access to tools — functions it can call to inspect and modify the project

Together these replace the need to paste documentation into a system prompt or rely on the agent's training data to know how Pulse works.

Resources: what the agent knows

The MCP server exposes read-only documents the agent fetches at any time. There are two top-level resources and a set of focused guide sections:

pulse://quickstart: Workflow phases, spec skeleton, component rules, and theming essentials combined into a single fetch. Used for targeted edits, bug fixes, or simple one-shot page builds — avoids loading the full guide for small tasks.
pulse://workflow: The full build workflow — every phase, pass gate, and ordering rule. The agent reads this before starting any new page or project.
pulse://persona: The quality bar the agent holds itself to: always write correct SSR, always handle errors, never skip empty states, never hardcode colours, never use data-event on text inputs. The persona defines what "done" means.

The guide is split into topic sections the agent fetches as needed:

pulse://guide/spec: Spec format — state, mutations, actions, streaming SSR, validation, key rules, and form layout.
pulse://guide/server: Server data fetchers, global store, persist, cookies, redirects, and POST handling.
pulse://guide/styles: CSS tokens, theming, custom fonts, and utility classes.
pulse://guide/routing: Client-side navigation, page discovery, and dynamic routes.
pulse://guide/components: All UI components and their props, icons, charts, and composition patterns.
pulse://guide/examples: Complete working page examples covering common patterns.
pulse://guide/templates: Pre-built landing page templates, adaptation rules, and theme CSS patterns. Fetched when building a new branded site or landing page.
pulse://guide/design-references: Twelve design directions with vibes, component combinations, palette patterns, and signature moves. Fetched during intake to pick the right aesthetic rather than defaulting to a generic SaaS look.
pulse://guide/design-gallery: All templates with visual descriptions and key components. Includes critical prop-name references and component recipes for cards, stat strips, and forms. Fetched when adapting a template or combining components.
pulse://guide/explore: Zone-based layout thinking, seven structural gestures, raw HTML patterns without components, and an anti-pattern checklist. Fetched when a distinctive or unusual layout is needed.

The guide is authoritative. When there is a question about how something should be structured — where state lives, how validation is wired, how streaming works — the guide answers it. The agent does not guess.

Tools: what the agent can do

The MCP server provides tools across five categories:

Design & intake

pulse_extract_inspiration: Extracts a structured design brief from a URL or image shared as inspiration. Called before pulse_intake when the user says "I like the look of X" — it tells the agent exactly what to observe and capture.
pulse_intake: Captures the product name, pitch, features, palette, vibe, and anti-style before scaffolding any new page or branded template. Returns a structured brief with copy-ready content, early contrast warnings, and component suggestions. Always runs before pulse_sketch.
pulse_sketch: Generates three structurally distinct layout directions (full-bleed, asymmetric split, editorial flow, etc.) before any code is written. Called after pulse_intake — prevents every project from defaulting to the same centred-hero layout.
pulse_intent: Intent engine — describe what you want to build and get back a matched archetype, recommended components, a ready-to-adapt spec scaffold, and which guide sections to read first. An alternative entry point to pulse://workflow for targeted tasks.
pulse_design_review: Reviews the built page's visual design against the original product brief from pulse_intake. Checks whether the design looks and feels appropriate for the product, audience, and vibe. Runs after screenshot, before Lighthouse.
pulse_layout_review: Multi-viewport layout review — checks for overflow, collapsed sections, and broken images at different screen widths. Runs after design approval but before Lighthouse, catching layout issues that Lighthouse doesn't flag.
pulse_tokens: Lists all available --ui-* CSS custom property tokens from the installed pulse-ui.css. Used before writing theme overrides to avoid guessing token names.
pulse_check_contrast: Static WCAG contrast checker. Extracts colour variable definitions from a theme file and checks common foreground/background pairings for WCAG AA compliance. Run immediately after writing a theme file to catch palette mistakes before Lighthouse.
pulse_check_csp: Resolves the redirect chains of external asset URLs (images, fonts, stylesheets) and returns the complete set of origins the CSP must allow. Many asset hosts redirect to a CDN origin — allowlisting only the URL you wrote still blocks the bytes. Run before the first Lighthouse pass on any page using external assets.

Scaffolding

pulse_create_page: Creates a new page spec file from a correct template. The filename determines the route — about.js becomes /about, posts/[slug].js becomes /posts/:slug. The file is written to src/pages/ and picked up by the server automatically.
pulse_create_component: Creates a reusable view component in src/components/. Components export named functions that return HTML strings — no classes, no JSX, no lifecycle hooks.
pulse_create_store: Creates a global store module in src/store/. Stores hold shared state (cart, user session, theme) that multiple pages can subscribe to and mutate.
pulse_create_action: Scaffolds a reusable server action — useful for shared form submission logic, API calls, or mutations that appear on more than one page.
pulse_create_tests: Generates a starter test file for a page spec — stubs the formulaic cases (null data, empty arrays, XSS injection, view landmarks, mutation logic, onViewError) so a page starts with coverage scaffolding instead of a blank file.

Inspection

pulse_status: Project health snapshot — pages, routes, server status, last build. Called at the start of a session to orient quickly without reading files individually.
pulse_list_structure: Lists every page, component, and store that already exists in the project. The agent calls this before creating anything — to avoid duplication and to understand what the codebase already provides.
pulse_fetch_page: Reads the full source of an existing spec file. Used when the agent needs to understand an existing page before editing it, or when a review of the current state is needed.
pulse_list_icons: Lists all available Pulse UI icon names, grouped by category. Called before importing icons — the agent never guesses a name.

Validation & review

pulse_validate: Validates a spec against the Pulse schema. Returns errors (which block progress) and warnings (which must also be resolved). The agent calls this after writing or editing every spec file. The identical check is also reachable from a terminal with no agent involved — pulse validate <file> runs the exact same shared logic and exits non-zero on failure, so it composes with a pre-commit hook or CI just like any other check.
pulse_suggest: Draft-mode feedback — paste a partial or complete spec and get constructive suggestions before running the hard validator. Unlike pulse_validate, it is collaborative rather than a gate: it notices patterns, spots likely omissions, and offers ideas. Used mid-build for a second opinion.
pulse_review: Switches the agent into reviewer mode. Returns the spec source, the rendered HTML output, and a structured checklist. Part of that checklist is mechanized — no LLM judgment involved, just a check that passes or fails: a conditionally-rendered modal (state.modalOpen), a POST form missing its CSRF token, a malformed _storeUpdate. The rest — accessibility, empty states, error handling, component usage, broader security — is a structured checklist the agent works through critically. Every issue found is fixed before continuing. The exact same mechanized checks are reachable without an agent: pulse review <file> (add --quick for the lightweight mid-build pass) runs the identical logic from a terminal, reported in plain language rather than as an instruction to an agent.
pulse_run_tests: Runs the project test suite (npm test) and returns the full output. Called after writing or editing specs to verify nothing is broken.
pulse_stamp: Writes the .pulse-verified stamp that clears the stop-hook verification gate. Called only as the last step of /verify — after Lighthouse passes on desktop and mobile and pulse_review is complete. A spec edited after the stamp was written blocks the session until verification runs again. Also marks any error-journal entries for the verified route as resolved.
pulse_diagnose: Reads the dev-only error journal (.pulse/errors.json) — server errors, SSR view throws, and post-hydration client view/action failures that would otherwise only appear as a console.error line no one's watching. Optionally filtered to one route. /verify calls this automatically before stamping a page; call it directly when something seems broken and the cause isn't obvious. Also reachable without an agent: pulse diagnose [--route /path] [--include-resolved] from the terminal, and pulse resolve-error --id <id> (or --route) to clear entries — both share this exact logic.
pulse_resolve_error: Marks journal entries resolved after fixing the underlying issue — by id or by route (every unresolved entry for that page at once). pulse_stamp already does this automatically for the route it verifies, so this is mainly for clearing an entry outside the /verify loop.
pulse_await_approval: Pauses the workflow gates for one turn-end, for a legitimate stopping point — a design-approval question, a progress update mid-verification. Lets the agent end its turn without the Stop hooks demanding /verify first. Consumed automatically on the user's next message; the gates return in full force after.

Server & maintenance

pulse_restart_server: Restarts the Pulse dev server. Called after structural changes — adding a new page, modifying the server entry — to reload all specs and re-register routes.
pulse_build: Builds the project for production. Bundles specs, hashes assets, and writes the manifest. Called when the agent needs to verify the production build or prepare a release.
pulse_check_bundles: Inspects what's actually inside the generated bundle files after pulse_build — not just their sizes. Lighthouse checks scores; this checks content. Flags a boot bundle generated for a page that doesn't need one (no mutations/actions/persist — should ship zero client JS), and a literal Node built-in reference inside a bundle (server-only code, e.g. a persistence layer using node:fs, that leaked through stripping instead of being caught by the build). Run as part of the full /verify pass, right after pulse_build. Also reachable without an agent: pulse check-bundles after pulse build runs this exact check from the terminal.
pulse_check_version: Reports the installed Pulse version and whether an update is available.
pulse_update: Updates the Pulse package to the latest version and copies the latest UI assets and agent files into the project.

What happens when you ask for something

Understand
Read the guide and inspect the project
The agent fetches pulse://workflow and the relevant pulse://guide/* sections, then calls pulse_list_structure to see every existing page, component, and store. Ambiguities are surfaced before any files are touched.
Plan
Present a plan — wait for confirmation
Before writing anything the agent describes what it intends to build: the route, state shape, server data, interactions, and any components or integrations it will use. The task does not proceed until you confirm.
Build
Write the spec and any supporting files
The spec is written as a plain JS object: route, state, server data, mutations, actions, view. The guide constrains every decision — where state lives, how validation is wired, how the view is structured.
Validate
Call pulse_validate — fix all errors and warnings
The spec is checked against the Pulse schema. Every error and warning is resolved before moving on — missing hydrate, heading order violations, missing escaping, structural mistakes. A clean output is the gate to the next phase.
Browser
Screenshot + Lighthouse — desktop and mobile
The agent navigates to the route, takes a screenshot to confirm the rendered output, then runs Lighthouse on both desktop and mobile. Accessibility, Best Practices, and SEO must all be 100. Any failure is fixed and re-verified before continuing.
Tests
Write tests, run them, fix failures
Unit tests cover any pure logic extracted from the spec. View tests use renderSync / render to assert HTML output. All tests must pass. When fixing a bug, a failing test is written first to pin the behaviour.
Review
Call pulse_review — only after phases 4–6 all pass
The agent switches into reviewer mode — reading the source and rendered output against the full spec checklist. Accessibility, empty states, error handling, component usage, and security are all checked. The review agent is always last.
Fix and re-verify
Fix every review issue — re-run affected gates
Every issue raised in review is resolved. Validate, Lighthouse, and tests are re-run to confirm all gates still pass. The task is complete only when every phase clears cleanly.
Done
The spec is the source of truth
Validate clean. Lighthouse 100. Tests passing. Review clear. No unresolved errors in the journal for this route. When every gate passes, the page is done — and the stamp write marks the route's error-journal entries resolved.

Why MCP instead of a system prompt

A system prompt is static — it cannot see your project, cannot validate your code, and cannot guarantee the agent uses the right version of the framework. The MCP server is dynamic: it reads the guide from the installed version of Pulse, inspects the actual files in your project, and calls real validation on the spec the agent just wrote.

The result is that the agent builds correctly on the first attempt far more often — not because it is smarter, but because the feedback loop is tighter and the knowledge is always current.