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 two resources the agent reads before doing any work:

pulse://guide — the complete framework reference, split into focused sections so each fits comfortably in a single read. The agent fetches whichever sections are relevant to the task at hand.
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 sections are:

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.

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 four categories:

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.

Inspection

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.

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.
pulse_review: Switches the agent into reviewer mode. Returns the spec source, the rendered HTML output, and a structured checklist covering accessibility, empty states, error handling, component usage, security, and correctness. The agent reads its own output critically and fixes every issue before continuing.

Server

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.

Maintenance

pulse_check_version: Reports the installed Pulse version and whether an update is available.
pulse_update: Updates the Pulse package to the latest version.

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. When all four gates pass, the page is done.

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.