MCP Server¶

Dazzle includes a built-in Model Context Protocol (MCP) server for seamless integration with Claude Code and other AI assistants.

Setup¶

# Homebrew (auto-registered on install)
brew install manwithacat/tap/dazzle

# PyPI (manual registration)
pip install dazzle-dsl
dazzle mcp setup

# Verify
dazzle mcp check

Consolidated Tools¶

The MCP server provides 24 consolidated tools (down from 66 original tools), plus 4 dev-mode project management tools. Each tool uses an operation parameter to select the action, reducing token overhead while preserving discoverability.

dsl¶

DSL parsing, validation, and introspection.

Operation	Purpose
`validate`	Parse and validate DSL files
`list_modules`	List project modules
`inspect_entity`	Examine entity definitions
`inspect_surface`	Examine surface definitions
`analyze`	Detect CRUD and integration patterns
`lint`	Extended validation with style checks
`get_spec`	Get DSL specification summary or details
`fidelity`	Check surface implementation fidelity
`list_fragments`	List UI fragments
`export_frontend_spec`	Export spec for frontend migration

knowledge¶

DSL concept lookup, examples, and workflow guides.

Operation	Purpose
`concept`	Look up DSL concepts and syntax
`examples`	Search example projects by features
`cli_help`	Get CLI command help
`workflow`	Get step-by-step workflow guides
`inference`	Find inference patterns
`get_spec`	Get DSL specification reference

story¶

Story-driven development and test generation.

Operation	Purpose
`propose`	Generate behavioural stories from DSL entities
`save`	Persist stories to project
`get`	Retrieve stories by status (use `view=wall` for board view)
`generate_tests`	Convert stories to test designs
`coverage`	Analyze story coverage

process¶

Workflow process inspection and visualization.

Operation	Purpose
`propose`	Generate process definitions from stories
`save`	Save process definitions
`list`	List all defined processes
`inspect`	Inspect process structure and steps
`list_runs`	List process execution runs
`get_run`	Get details of a specific run
`diagram`	Generate Mermaid diagrams (flowchart or state)
`coverage`	Process coverage analysis

test_design¶

UX test coverage and test design management.

Operation	Purpose
`propose_persona`	Generate tests from persona goals
`gaps`	Identify untested areas
`save`	Persist test designs
`get`	Retrieve test designs by status
`coverage_actions`	Get prioritized actions to increase coverage
`runtime_gaps`	Analyze runtime coverage report
`save_runtime`	Save runtime coverage report
`auto_populate`	Auto-populate stories and test designs
`improve_coverage`	Suggest coverage improvements

demo_data¶

Generate demo and seed data from DSL.

Operation	Purpose
`propose`	Generate demo data blueprint from DSL
`save`	Save blueprint to project
`get`	Retrieve current blueprint
`generate`	Generate CSV/JSONL demo data files

api_pack¶

External API integrations.

Operation	Purpose
`list`	List available API packs
`search`	Search integrations by category or provider
`get`	Get full API pack details
`generate_dsl`	Generate DSL from API pack
`env_vars`	Get `.env.example` content for packs

sitespec¶

Public website specification and theming.

Operation	Purpose
`get`	Get site configuration
`validate`	Validate site for semantic correctness
`scaffold`	Create default site structure
`coherence`	Check if site feels like a real website
`review`	Page-by-page spec vs rendering comparison
`get_copy`	Get site copy
`scaffold_copy`	Generate site copy
`review_copy`	Review site copy
`get_theme`	Get theme configuration
`scaffold_theme`	Generate theme from brand parameters
`validate_theme`	Validate theme
`generate_tokens`	Generate design tokens
`generate_imagery_prompts`	Generate image prompts from brand

semantics¶

Event-first architecture analysis.

Operation	Purpose
`extract`	Extract semantic elements from AppSpec
`validate_events`	Validate event naming and idempotency
`tenancy`	Infer multi-tenancy requirements
`compliance`	Infer compliance requirements (GDPR, PCI)
`analytics`	Infer analytics intent and data products
`extract_guards`	Extract guard conditions

graph¶

Knowledge graph for codebase understanding.

Operation	Purpose
`query`	Search entities by text
`dependencies`	What does X depend on?
`dependents`	What depends on X?
`neighbourhood`	Entities within N hops
`paths`	Find paths between entities
`stats`	Graph statistics
`populate`	Refresh graph from source
`concept`	Look up a framework concept
`inference`	Find inference patterns
`related`	Get related concepts for an entity

dsl_test¶

API-level test generation and execution.

Operation	Purpose
`generate`	Generate tests from DSL definitions
`run`	Run a specific test
`run_all`	Run all tests against a server
`coverage`	Show test coverage
`list`	List available tests
`create_sessions`	Create authenticated sessions for personas
`diff_personas`	Compare responses across personas
`verify_story`	Verify a story against API tests

e2e_test¶

End-to-end testing with Playwright.

Operation	Purpose
`check_infra`	Check Playwright infrastructure
`run`	Run E2E tests
`run_agent`	Run LLM-agent-powered E2E tests
`coverage`	E2E coverage analysis
`list_flows`	List test flows
`tier_guidance`	Get testing tier guidance for a scenario
`run_viewport`	Run viewport/responsive tests

discovery¶

Capability discovery — explore a running app as a persona.

Operation	Purpose
`run`	Build and run a discovery mission
`report`	Get discovery results
`compile`	Convert observations to proposals
`emit`	Generate DSL from proposals
`status`	Check readiness
`verify_all_stories`	Batch verify stories against API tests

pipeline¶

Full deterministic quality audit in a single call.

Operation	Purpose
`run`	Chain: validate, lint, fidelity, tests, coverage, semantics

pulse¶

Founder-ready project health report.

Operation	Purpose
`run`	Full report with narrative and launch readiness score
`radar`	Compact 6-axis readiness chart
`persona`	View app through a specific persona's eyes
`timeline`	Project timeline view
`decisions`	Decisions needing founder input

composition¶

Visual composition analysis.

Operation	Purpose
`audit`	DOM-level visual hierarchy audit
`capture`	Take section-level screenshots
`analyze`	LLM visual evaluation of screenshots
`report`	Combined audit + visual analysis
`bootstrap`	Generate reference library for evaluation
`inspect_styles`	Extract computed CSS styles

bootstrap¶

Entry point for "build me an app" requests.

Operation	Purpose
(default)	Scaffold a new app from a natural language description

spec_analyze¶

Analyze narrative specs before DSL generation.

Operation	Purpose
`discover_entities`	Extract entities from a narrative spec
`identify_lifecycles`	Find state machines and workflows
`extract_personas`	Identify user personas from descriptions

policy¶

RBAC access control analysis.

Operation	Purpose
`analyze`	Analyze access rules across surfaces
`conflicts`	Detect conflicting permissions
`coverage`	Measure RBAC coverage gaps
`simulate`	Simulate access for a persona/route

pitch¶

Generate investor pitch materials from DSL.

Operation	Purpose
`scaffold`	Create pitch structure
`generate`	Generate pitch deck content
`validate`	Validate pitch completeness
`review`	Review and improve pitch
`enrich`	Enrich with market data

contribution¶

Package contributions for sharing.

Operation	Purpose
`templates`	List available contribution templates
`create`	Create a contribution package
`validate`	Validate contribution format
`examples`	Browse example contributions

user_management¶

Manage auth users and sessions.

Operation	Purpose
`list`	List users
`create`	Create a user
`get`	Get user details
`update`	Update user properties
`deactivate`	Soft-delete a user

user_profile¶

Adaptive persona inference.

Operation	Purpose
(default)	Infer the current user's persona from context

Usage Examples¶

Validating a project:

User: "Validate my DAZZLE project"
Claude: [Uses dsl tool with operation=validate]
        "Found 3 modules, 5 entities, 8 surfaces. All valid."

Inspecting an entity:

User: "What fields does the Task entity have?"
Claude: [Uses dsl tool with operation=inspect_entity, name=Task]
        "Task has 6 fields: id (uuid pk), title (str required), ..."

Generating stories:

User: "Propose user stories for my app"
Claude: [Uses story tool with operation=propose]
        "Generated 12 stories covering Task CRUD and status transitions..."

Running quality audit:

User: "How's the project health?"
Claude: [Uses pulse tool with operation=run]
        "Launch Readiness: 72%. Strengths: DSL coverage, API tests.
         Gaps: Missing persona tests, 2 surfaces below fidelity threshold."

Visualizing a process:

User: "Show me the order fulfillment workflow"
Claude: [Uses process tool with operation=diagram]
        "Here's a Mermaid flowchart showing the 5-step process..."

Configuration¶

The MCP server is registered at ~/.claude/settings.json (Claude Code) or ~/.config/claude/claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "dazzle": {
      "command": "dazzle",
      "args": ["mcp", "run"]
    }
  }
}

For Homebrew installations, this is configured automatically via dazzle mcp setup.

Per-project vs. global configuration¶

Prefer a project-scoped MCP entry over a single global, framework-rooted one.

When the server's working directory is a framework checkout (a clone of Dazzle itself — no dazzle.toml, but src/dazzle/ + examples/ present), it runs in dev mode: it only discovers the example apps under examples/ and never auto-selects one. That is correct for working on the framework, but if you point one global MCP entry at the framework checkout and then open an unrelated project, two silent traps follow (#1374):

Concurrent sessions collide. The MCP lock is keyed per project root (<root>/.dazzle/mcp.lock) to stop two servers racing the knowledge-graph SQLite WAL. A global config pins one root for every session, so the second session to boot fails with "Another DAZZLE MCP server is already running."
Other projects are mis-rooted. A project living outside examples/ is invisible to a framework-rooted server. Project tools either error ("No project selected…") or operate on the framework-dev install — the wrong knowledge graph and an unexpectedly-old dazzle version, so e.g. dsl validate may reject newer grammar your project legitimately uses.

The fix is to give each project its own MCP entry pointed at that project, using the project's own interpreter:

{
  "mcpServers": {
    "dazzle-myproject": {
      "command": "/path/to/MyProject/.venv/bin/python",
      "args": ["-m", "dazzle.mcp", "--working-dir", "/path/to/MyProject"]
    }
  }
}

Each project-scoped entry gets its own lock, its own knowledge graph, and the dazzle version pinned in that project's environment. Reserve a framework-rooted entry (--working-dir <dazzle-checkout>) for working in the framework repo, and use select_project to choose among its example apps.

Internal Architecture¶

The MCP server uses consolidated handlers for maintainability:

src/dazzle/mcp/server/
├── __init__.py                  # Server setup and routing
├── tools_consolidated.py        # Tool definitions (24 consolidated + 4 dev-mode)
├── handlers_consolidated.py     # Dispatch: operation → handler function
├── handlers/
│   ├── dsl.py                   # DSL parsing, entity/surface inspection
│   ├── knowledge.py             # Concept lookup, workflow guides
│   ├── stories.py               # Story generation, test conversion
│   ├── process.py               # Process inspection, diagrams
│   ├── test_design.py           # Test coverage, persona tests
│   ├── demo_data.py             # Demo data generation
│   ├── api_packs.py             # External API integrations
│   ├── sitespec.py              # Site specification and theming
│   ├── semantics.py             # Event-first architecture analysis
│   ├── discovery.py             # Capability discovery missions
│   ├── dsl_test.py              # API test generation and execution
│   ├── e2e_test.py              # E2E Playwright tests
│   ├── pipeline.py              # Quality audit pipeline
│   ├── pulse.py                 # Project health reports
│   ├── composition.py           # Visual composition analysis
│   ├── policy.py                # RBAC access control analysis
│   ├── status.py                # MCP + runtime status and activity
│   └── ...
├── state.py                     # Project state management
├── progress.py                  # Progress reporting
└── activity_log.py              # Activity logging (JSONL + SQLite)

Troubleshooting¶

Server not starting¶

# Check MCP status
dazzle mcp check

# View logs
dazzle mcp run --debug

Tool not found¶

Ensure you have the latest version:

brew upgrade manwithacat/tap/dazzle
# or
pip install --upgrade dazzle-dsl

"Another DAZZLE MCP server is already running"¶

A second Claude Code session can't start the MCP because the per-root lock is already held. This usually means a single global MCP entry rooted at a framework checkout is shared by every session — see Per-project vs. global configuration. Give each project its own --working-dir <project> entry so it gets its own lock. (To release a genuinely stale lock, the failure message prints the holder PID and a kill command.)

Project tools return "No project selected" or operate on the wrong version¶

The MCP is in dev mode (rooted at a framework checkout) and your project lives outside examples/, so it isn't discovered. Either select_project (for example apps), pass project_path explicitly, or — for a real project — configure a project-scoped MCP entry as above. A framework-rooted server runs the framework-dev dazzle, not your project's pinned wheel, which is why dsl validate can reject grammar your project legitimately uses.