Vibe Coding MCP Server

An MCP server that brings the Vibe Coding journey to any LLM host (Kiro, Claude Code, Codex, Cursor, …) — without running the builder-render app.

Its primary audience is developers who just want production-ready TSX built with the OB component library and @bolttech/form-engine for their own flow. Builder.io is entirely optional.

What it exposes

Context resources (Builder-independent — the core value):

• vibe-coding://context/ob-figma-component-map — OB ↔ Figma component map
• vibe-coding://context/vibe-coding-tsx-generator — TSX generation rules
• vibe-coding://context/form-schema-generator — OB mapper + theme tables
• vibe-coding://context/form-engine-external — form-engine API guide
• vibe-coding://context/accessibility-guidance — WCAG 2.1 AA / EAA page-composition rules
• vibe-coding://context/navigation-bindings — screen-to-screen navigation binding contract (FormEngine root, submit-typed trigger, Router provider, onSubmitFormEngine)
• vibe-coding://context/theme-tokens — derived theme-token reference

These are read from the repo's steering files on demand, so edits propagate without restarting the server.

Tools (skills), at a glance:

| Tool | Needs | Purpose | |------|-------|---------| | generate_guidance | — | Assembled guidance for generating OB + form-engine TSX. | | ask_form_engine | — | Answers form-engine "how do I…" questions. | | write_component | — | Writes generated TSX into your project. | | audit_accessibility | — | Audits a URL/markup/file against the accessibility guidance. Never writes. | | apply_accessibility_fixes | — | Applies specific approved findings from a prior audit. | | open_vibe_coding | — | Opens the hosted Vibe Coding screen. | | preview_screen | Redis | Publishes a screen to Redis, returns a hosted-screen URL. | | tsx_to_blocks_preview | Builder (optional) | Converts TSX to Builder.io blocks. | | push_symbol | Builder | Pushes a TSX component as a Builder.io symbol. | | push_as_page | Builder | Publishes a TSX component as a routable Builder.io page. |

The Builder-backed tools are always listed for discoverability; when Builder is not configured they return an actionable error naming the missing variable — they never take the server down.

Tool reference

Each tool below lists its inputs. Fields marked (optional) may be omitted.

generate_guidance — Generate TSX Guidance (no Builder)

Returns a host-agnostic instruction bundle (component map, TSX rules, form-engine API, theme tokens) for generating OB-component + form-engine TSX.

• designDescription (optional) — description of the screen to build; echoed into the guidance so the LLM keeps the task in context.
• includeThemeTokens (optional, boolean) — include the derived theme-token reference (default: true).

ask_form_engine — Ask Form Engine (no Builder)

Answers a form-engine "how do I…" question (visibility conditions, validations, masks, formatters, resetValues, templating, events, screen-to-screen navigation) grounded in the form-engine guide and the navigation binding contract.

• question (required) — e.g. "how do I make a field appear only when another equals yes?".

write_component — Write Component To Project (no Builder)

Writes generated TSX into your own project, confined to VIBE_CODING_OUTPUT_ROOT (defaults to the working directory).

• relativePath (required) — destination path relative to the output root (e.g. src/screens/LoginPage.tsx). Absolute paths or paths escaping the root are rejected.
• content (required) — the full file contents to write.
• overwrite (optional, boolean) — overwrite if the file exists (default: false).

audit_accessibility — Audit Accessibility (no Builder)

Audits a target against the bolttech accessibility guidance (WCAG 2.1 AA / EAA). Static analysis only — it reads markup and CSS but never executes JavaScript, so client-rendered content is not evaluated, and a clean result is not a conformance certificate; manual testing with assistive technologies is still required. The audit is built for pages using the bolttech design system — pasting an unrelated site returns a "does not use our components" result with generic guidance only, no located fixes. This tool never writes anything.

• url (optional) — an https URL to audit. Provide exactly one of url, source, or filePath.
• source (optional) — inline markup or TSX, analysed with no network or file access.
• filePath (optional) — a file inside the output root.
• stylesheet (optional) — an explicit stylesheet (project-relative path or https URL) for targets whose CSS is not discoverable from the markup. Without it, colour-dependent findings cannot be evaluated.

Findings are classified pageLevel (fixable via apply_accessibility_fixes), designSystem (the offending markup is an OB component's own output — contact the design team), or token (the failure traces to a design token value with no page-level alternative — also contact the design team). Only pageLevel findings with a resolved project location are ever applicable.

apply_accessibility_fixes — Apply Accessibility Fixes (no Builder)

Applies specific findings from a prior audit_accessibility call, confined to the output root. Re-reads each target file and skips a finding as stale if the source changed since the audit, rather than overwriting it blind.

• auditId (required) — the id returned by audit_accessibility.
• findingIds (required, array) — the specific finding ids to apply.

open_vibe_coding — Open Vibe Coding Screen (no Builder)

Opens the hosted Vibe Coding screen (preview, optional push to Builder, or just take the generated TSX).

• url (optional) — override for the screen URL; defaults to the server-configured VIBE_CODING_URL.

preview_screen — Preview Generated Screen (needs Redis)

Publishes a render-ready screen to Redis and returns a hosted Vibe Coding URL that renders it — no local builder-render or repo access needed. See Preview screens with Redis.

• tsxCode (optional) — the TSX source to preview. Provide this or filePath.
• filePath (optional) — path to a TSX file relative to the output root (read instead of pasting tsxCode).
• symbolName (optional) — display name shown for the preview.

tsx_to_blocks_preview — Preview TSX as Builder Blocks (Builder, optional)

Converts TSX into Builder.io blocks so you can preview the output before pushing. Not needed if you only want the TSX.

• tsxCode (required) — the TSX source to convert into Builder.io blocks.

push_symbol — Push TSX as Builder Symbol (needs Builder)

Pushes a TSX component as a symbol to Builder.io. Requires BUILDER_PRIVATE_KEY; returns an actionable error when unconfigured.

• tsxCode (required) — the TSX source to push as a symbol.
• entryName (optional) — name for the created symbol entry.
• fileName (optional) — source file name recorded on the symbol.
• themeName (optional) — theme name stored on the symbol entry.
• navigationIntents (optional) — array of { trigger, destination } to wire a real onSubmitFormEngine navigation binding onto this symbol. See Wiring navigation below.

push_as_page — Push TSX as Builder Page (needs Builder)

Publishes a TSX component as a routable page (url + title, not a symbol) using the same block/provider assembly as push_symbol. This is what lets a host generate a full navigable flow entirely through the MCP: generate each screen with generate_guidance, pass navigationIntents so this tool wires a real onSubmitFormEngine binding per the navigation-bindings contract (see the navigation-bindings context resource or ask ask_form_engine), then call push_as_page once per screen so every destination resolves to a real, live route. Requires BUILDER_PRIVATE_KEY. Always creates a new page — it does not collision-check the URL first, so pick distinct routes per screen.

• tsxCode (required) — the TSX source to publish as a page.
• title (required) — page title, also used as the Builder entry name.
• url (optional) — target route (e.g. /checkout); normalized to lowercase kebab-case with a single leading slash. Defaults to a slug derived from title when omitted. Must match whatever a navigation binding pushes to, or that binding 404s.
• themeName (optional) — theme name stored on the page entry.
• navigationIntents (optional) — array of { trigger, destination } to wire a real onSubmitFormEngine navigation binding onto this page. See Wiring navigation below.

Wiring navigation (navigationIntents)

Both push_symbol and push_as_page accept an optional navigationIntents array so a host can build a fully navigable multi-screen flow without leaving the MCP:

{
  "navigationIntents": [
    { "trigger": "continueBtn", "destination": "/checkout" }
  ]
}

• trigger — the navigating button's name prop (preferred) or its visible title, exactly as it appears in tsxCode.
• destination — a route (/checkout) or screen name ("Payment Screen"); normalized to a lowercase kebab-case path with a single leading slash.

Before pushing, the tool parses tsxCode into Builder blocks, matches each trigger against the buttons actually generated, and — for each match — sets that button's type to submit and attaches a real Builder custom-code binding (onSubmitFormEngine) on its FormEngine root that calls context.router.push(destination). This is a genuine Builder binding editable in the visual editor, not a useRouter call baked into the TSX — it only works because the page also carries the Router provider (added automatically via resolveProviders), per the navigation-bindings contract.

An intent whose trigger doesn't match any generated button, or whose form index already has a destination, is reported back as unwired (with the reason) in the tool's response text — it is never guessed or silently dropped. At most one destination is supported per form index, since onSubmitFormEngine holds a single action and the submit payload carries no identifier of which field submitted.

Install

External developers do not need this repo. Install from npm:

npm install -g @bolttech/vibe-coding-mcp
# or run on demand without installing:
npx -y @bolttech/vibe-coding-mcp

The published package is self-contained: the steering context files ship inside it (under context/), so the context resources resolve with no repo checkout and no access to builder-render.

Running the server

The server speaks MCP; it is normally launched by an MCP host (see Connecting from an MCP host), but you can run it directly for testing.

stdio transport (default) — the mode MCP hosts use. The process reads/writes JSON-RPC over stdio and stays attached to the host:

# on demand (no install)
VIBE_CODING_URL="http://localhost:3000/vibe-coding" npx -y @bolttech/vibe-coding-mcp

# after a global install
VIBE_CODING_URL="http://localhost:3000/vibe-coding" vibe-coding-mcp

On startup it logs one line to stderr, e.g. [vibe-coding-mcp] stdio transport ready (Builder-free).

HTTP transport — exposes a streamable HTTP endpoint at POST /mcp instead of stdio (see the security note at the end before using it):

MCP_TRANSPORT=http MCP_HTTP_PORT=3845 \
  VIBE_CODING_URL="http://localhost:3000/vibe-coding" \
  npx -y @bolttech/vibe-coding-mcp

Configuration

All configuration is via environment variables provided by your MCP host's env block (see recipes below). Everything Builder/Jira-related is optional.

When running from a checkout of this monorepo, the server also reads apps/builder-render/.env.local as a convenience; external installs ignore it and rely solely on env (or an explicit VIBE_CODING_ENV_FILE).

| Variable | Required for | Default | |----------|--------------|---------| | VIBE_CODING_URL | open_vibe_coding / preview_screen base | stage screen URL | | VIBE_CODING_REDIS_URL | preview_screen | — | | VIBE_CODING_PREVIEW_TTL_SECONDS | preview TTL | 1800 | | VIBE_CODING_OUTPUT_ROOT | write_component write boundary | working dir | | MCP_TRANSPORT | transport selection (stdio | http) | stdio | | MCP_HTTP_PORT | HTTP transport port | 3845 | | BUILDER_PRIVATE_KEY | push_symbol | — | | BUILDER_API_KEY / BUILDER_API_URL | push provider lookup | — | | JIRA_TOKEN / JIRA_MCP_URL | ticket-rules flows (optional) | — |

Preview screens with Redis (preview_screen)

The preview_screen tool publishes a render-ready screen to Redis and returns a hosted Vibe Coding URL that renders it — so you can preview generated TSX without running builder-render locally or having repo access. Redis is the transport the hosted screen reads from; it is entirely optional and only this one tool needs it.

How it works: the tool writes a JSON record under the key chatbot-preview:{correlationId} with a native TTL, then returns a URL of the form {VIBE_CODING_URL}?preview={correlationId}. The hosted screen reads that key and renders the screen. The record expires automatically after the TTL.

Enable it by setting the Redis connection URL (a bare host:port is also accepted and gets a redis:// scheme prepended):

| Variable | Purpose | Default | |----------|---------|---------| | VIBE_CODING_REDIS_URL | Redis connection (redis://… or rediss://…); enables preview_screen | — (tool disabled) | | VIBE_CODING_PREVIEW_TTL_SECONDS | TTL applied to each preview record | 1800 | | VIBE_CODING_URL | Base URL of the hosted screen the returned link points at | stage screen URL |

{
  "mcpServers": {
    "vibe-coding": {
      "command": "npx",
      "args": ["-y", "@bolttech/vibe-coding-mcp"],
      "env": {
        "VIBE_CODING_URL": "http://localhost:3000/vibe-coding",
        "VIBE_CODING_REDIS_URL": "redis://localhost:6379",
        "VIBE_CODING_PREVIEW_TTL_SECONDS": "1800"
      },
      "disabled": false
    }
  }
}

When VIBE_CODING_REDIS_URL is not set, preview_screen stays listed but returns an actionable error naming the missing variable; every other capability keeps working. The Redis key contract (chatbot-preview:{id}) matches what the builder-render app already reads, so previews render identically.

Build

npx nx build vibe-coding-mcp
# Produces a publishable dist at dist/libs/vibe-coding-mcp/ containing:
#   main.js         self-contained bundle (workspace core inlined)
#   package.json    runtime deps stay external (@modelcontextprotocol/sdk, redis, zod)
#   context/*.md    steering context shipped with the package
#   README.md

Connecting from an MCP host

Add one of the following to your host's mcp.json (e.g. ~/.kiro/settings/mcp.json). These use npx, so no clone or local build is required.

1. Builder-free minimal setup (recommended for TSX-only)

Serves context + generate_guidance + open_vibe_coding. No Builder needed.

{
  "mcpServers": {
    "vibe-coding": {
      "command": "npx",
      "args": ["-y", "@bolttech/vibe-coding-mcp"],
      "env": {
        "VIBE_CODING_URL": "http://localhost:3000/vibe-coding"
      },
      "disabled": false,
      "autoApprove": ["generate_guidance"]
    }
  }
}

2. Full setup (enables the Builder-backed tools)

Adds tsx_to_blocks_preview and push_symbol.

{
  "mcpServers": {
    "vibe-coding": {
      "command": "npx",
      "args": ["-y", "@bolttech/vibe-coding-mcp"],
      "env": {
        "VIBE_CODING_URL": "http://localhost:3000/vibe-coding",
        "BUILDER_PRIVATE_KEY": "bpk-xxxxxxxxxxxxxxxx",
        "BUILDER_API_KEY": "your-builder-public-key",
        "BUILDER_API_URL": "https://cdn.builder.io/api"
      },
      "disabled": false,
      "autoApprove": ["generate_guidance"]
    }
  }
}

Contributors working inside this monorepo can instead point command at node with args: ["dist/libs/vibe-coding-mcp/main.js"] after running npx nx build vibe-coding-mcp.

Context is a per-version snapshot

The steering context shipped in the package reflects the repo at publish time. To propagate steering edits to consumers, bump the version and publish again (npx nx run vibe-coding-mcp:version). Contributors running from a checkout always read the live steering files instead.

HTTP transport — security note

Setting MCP_TRANSPORT=http exposes a streamable HTTP endpoint at POST /mcp. This endpoint is UNAUTHENTICATED. Only run it behind your own network controls (bind to localhost, a private network, or an authenticating reverse proxy). Never expose it directly to an untrusted network.