mdma-integration

name	mdma-integration
description	Integrate MDMA into an application and build features with it — wire up parsing, the runtime store, React rendering, LLM streaming, custom components, prompts, and CI validation. Use this skill when the user asks to add MDMA to an app, build a chat that streams MDMA, author or maintain a custom prompt, validate MDMA documents, register a custom component, or expose MDMA to an agent via MCP. Generates focused, correct wiring that uses the right packages for the job instead of reinventing them.
license	MIT

This skill guides integration of MDMA (Markdown Document with Mounted Applications) into real applications. MDMA is published as a set of composable npm packages under the @mobile-reality org — mdma-spec, mdma-parser, mdma-runtime, mdma-renderer-react, mdma-attachables-core, mdma-prompt-pack, mdma-validator, mdma-cli, mdma-mcp. A good integration picks the narrowest set of packages for the task, follows the parse → store → render contract, and uses the authoring and validation tooling rather than rolling its own. The goal is to make it obvious to a developer — or an agent — how to plug MDMA into their stack with minimum ceremony and maximum correctness.

The user provides an integration task: "add MDMA to this React chat app", "stream MDMA from the LLM and re-render as chunks arrive", "write a domain prompt for a clinical intake", "validate our MDMA docs in CI", "register a custom chart renderer", "expose MDMA to our agent via MCP", or "migrate our form rendering to MDMA". They may specify framework (React is first-class), LLM provider, validation rules, or PII constraints.

Integration Thinking

Before editing code, establish what "integrate MDMA" actually means for this request:

• Shape of the integration: One of — static document rendering (ship pre-written MDMA, parse+render once), LLM-streamed chat (assistant streams MDMA, reparse as chunks arrive, preserve store state across reparses), CI validation (lint *.md files against the spec), custom prompt authoring (build a domain-specific customPrompt that feeds buildSystemPrompt), MCP exposure (let an agent call get-spec / build-system-prompt / validate-prompt), or custom component (register a Zod schema + renderer for a non-builtin type). Each has a different package footprint.
• Package footprint: Install only what the integration needs. A chat app needs mdma-parser + mdma-runtime + mdma-renderer-react + mdma-prompt-pack. A CI validator needs only mdma-validator. An agent harness may need only mdma-mcp. Don't install the full matrix "just in case" — the dependency graph is structured so you never have to.
• Constraints: Which components are in scope? Which fields must be sensitive? Which environment policies apply (allow/deny actions, redaction mode)? Which LLM provider is streaming? Does the host app already own state management, or will createDocumentStore be the source of truth for document state?
• Where prompts live: A domain prompt is a maintained artifact, not a one-off string. Decide where it lives (a prompts/ directory, exported from a package, generated via the CLI prompt builder) and how it's versioned, before writing it.

CRITICAL: Integrate with the smallest valid surface area. Prefer the provided MdmaDocument + createDocumentStore pairing over hand-rolled rendering. Prefer buildSystemPrompt({ customPrompt }) over concatenating strings yourself. Prefer the validator package over ad-hoc regex. The packages encode invariants (binding graph, PII redaction, audit log, policy) that are painful to re-derive.

MDMA Integration Guidelines

Focus on:

• Package selection & dependency chain: The core chain is spec → parser → runtime → attachables-core → renderer-react. prompt-pack, validator, cli, mcp are leaves that depend only on spec. Install the minimum footprint for the task:

  # Parse + run MDMA documents (headless)
  npm install @mobile-reality/mdma-parser @mobile-reality/mdma-runtime
  
  # Add React rendering
  npm install @mobile-reality/mdma-renderer-react
  
  # LLM authoring — domain system prompts
  npm install @mobile-reality/mdma-prompt-pack
  
  # CI / static analysis
  npm install @mobile-reality/mdma-validator
  

  Never reinstall peers that are already pulled transitively.

• Parse → Store → Render: The contract is non-negotiable. Build a unified().use(remarkParse).use(remarkMdma) processor once (module-level singleton), feed it markdown, pass the AST to createDocumentStore, pass both to <MdmaDocument>:

  import { unified } from 'unified';
  import remarkParse from 'remark-parse';
  import { remarkMdma } from '@mobile-reality/mdma-parser';
  import { createDocumentStore } from '@mobile-reality/mdma-runtime';
  import { MdmaDocument } from '@mobile-reality/mdma-renderer-react';
  import '@mobile-reality/mdma-renderer-react/styles.css';
  import type { MdmaRoot } from '@mobile-reality/mdma-spec';
  
  const processor = unified().use(remarkParse).use(remarkMdma); // singleton
  
  const tree = processor.parse(markdown);
  const ast = (await processor.run(tree)) as MdmaRoot;
  const store = createDocumentStore(ast, {
    documentId: 'my-doc',
    sessionId: crypto.randomUUID(),
  });
  
  return <MdmaDocument ast={ast} store={store} />;
  

• LLM streaming: The hard part of chat integrations is that the LLM emits MDMA token-by-token, but you can't re-createDocumentStore on every chunk (you'd wipe user state). The right pattern: throttle reparse (~150ms), and on each reparse call existingStore.updateAst(newAst) instead of building a fresh store. This preserves bindings, focus, and in-flight form edits across reparses.

  // On each ~150ms tick while streaming:
  const tree = processor.parse(message.content);
  const newAst = (await processor.run(tree)) as MdmaRoot;
  if (existingStore) {
    existingStore.updateAst(newAst); // preserves user state
  } else {
    existingStore = createDocumentStore(newAst, { documentId, sessionId });
  }
  

  Copy this shape; do not invent a replacement.

• Prompts — build, don't concatenate: Use buildSystemPrompt({ customPrompt }) from @mobile-reality/mdma-prompt-pack. It sandwiches your domain rules between the MDMA spec and a reinforcement tail — the ordering matters for model adherence. Your customPrompt should name the domain, allowed components, required fields, sensitive fields, trigger conditions, and business rules. A vague "help the user" prompt produces generic forms; a prompt that encodes the domain produces documents that fit the product. When the prompt grows non-trivial, use the CLI prompt builder (npx @mobile-reality/mdma-cli) to generate it structurally, then commit the result as a maintained file.

  import { buildSystemPrompt } from '@mobile-reality/mdma-prompt-pack';
  
  const systemPrompt = buildSystemPrompt({
    customPrompt: `Domain: clinical intake.
  Allowed components: form, approval-gate, callout.
  All PII fields (name, email, phone, DOB, MRN) MUST be sensitive: true.
  Generate MDMA when the user describes a patient visit or symptom.`,
  });
  

• Prompt maintenance rules: Treat every custom prompt as code. Version it. Keep it in a file, not inline. Re-run the evals after changes. When updating, prefer adding a constraint to rewriting the prompt — additive changes preserve prior eval coverage. Name the file after the domain (e.g. prompts/clinical-intake.ts), not the author.

• Validation: In CI, call validate(markdown, { autoFix: false }) from @mobile-reality/mdma-validator and fail the job on !result.ok. For local DX, wire npx @mobile-reality/mdma-cli validate "docs/**/*.md" --fix. Do not write custom YAML-regex linters — the validator already covers YAML correctness, schema conformance, ID uniqueness, binding resolution, and PII sensitivity.

  import { validate } from '@mobile-reality/mdma-validator';
  
  const result = await validate(markdown, { autoFix: false });
  if (!result.ok) {
    for (const issue of result.issues) console.error(issue);
    process.exit(1);
  }
  

• Custom components: To add a non-builtin component type, define a Zod schema, pass it to the parser via customSchemas, and register a React renderer via customizations.components.<type> on MdmaDocument. The same slot overrides built-ins (e.g. swap the default table-fallback chart for a recharts renderer).

  import { z } from 'zod';
  import { ComponentBaseSchema } from '@mobile-reality/mdma-spec';
  
  const ProgressSchema = ComponentBaseSchema.extend({
    type: z.literal('progress'),
    value: z.number().min(0).max(100),
  });
  
  const processor = unified()
    .use(remarkParse)
    .use(remarkMdma, { customSchemas: new Map([['progress', ProgressSchema]]) });
  
  <MdmaDocument
    ast={ast}
    store={store}
    customizations={{
      components: {
        progress: ProgressRenderer,
        chart: MyRechartsRenderer, // overrides the built-in table fallback
      },
    }}
  />;
  

• Actions & events: Subscribe to the event bus via store.getEventBus().onAny(handler) to observe user actions without coupling to React state. Dispatch programmatically with store.dispatch({ type: 'FIELD_CHANGED' | 'ACTION_TRIGGERED' | ... }). Multi-step flows listen for ACTION_TRIGGERED and advance the conversation (e.g. inject the next assistant message when a button fires).

• Agent integrations via MCP: When an agent (Claude Desktop, Cursor, a custom harness) needs to produce MDMA, wire @mobile-reality/mdma-mcp instead of bundling prompts into the agent. Its tools — get-spec, get-prompt, build-system-prompt, validate-prompt, list-packages — collapse the discovery phase so the agent gets the spec, packages, and ready-made prompts in a handful of tool calls. The integration is three lines of JSON in the agent's MCP config:

  {
    "mcpServers": {
      "mdma": { "command": "npx", "args": ["@mobile-reality/mdma-mcp"] }
    }
  }
  

• Blueprints as starting points: The upstream MDMA repository ships five production-shaped blueprints (change-management, clinical-ops, customer-escalation, incident-triage, kyc-case). When scaffolding a new domain, copy the nearest blueprint from the upstream repo and adapt — don't start from a blank file. They encode real component mixes, field choices, and flow shapes.

NEVER ship these integration anti-patterns:

• Re-creating createDocumentStore(ast) on every streamed chunk instead of calling store.updateAst(ast) — wipes user input mid-typing
• Rebuilding the unified processor on every render — it's expensive; make it a module-level singleton
• Concatenating system prompt strings by hand instead of calling buildSystemPrompt — breaks the spec + reinforcement sandwich the model relies on
• Writing regex-based validators instead of calling validate() — misses binding-graph and schema-conformance issues the package already catches
• Installing every @mobile-reality/mdma-* package when the integration only needs two or three
• Copy-pasting the MDMA spec into your system prompt instead of importing MDMA_AUTHOR_PROMPT / calling buildSystemPrompt — the spec evolves with the package
• Registering custom components only as renderers, without a matching Zod schema — the parser will reject the block or silently drop it
• Letting sensitive fields through unmarked because the prompt didn't require them — add "All PII fields must be marked sensitive" to every domain prompt by default
• Hardcoding a chart library into a fork of renderer-react — use customizations.components.chart instead
• Treating the generated prompt from mdma-cli as ephemeral — it's the domain spec; commit it

Interpret pragmatically and pick the shallowest integration that satisfies the requirement. A one-page demo that renders a static MDMA file needs three imports and ten lines. A production chat with streaming, custom components, and CI validation needs the full stack. Don't converge on a default kitchen-sink wiring across integrations.

IMPORTANT: Match integration depth to the app's vision. A static document viewer wants parser + renderer-react and nothing else — no store events, no prompt pack, no validator. A domain chat platform wants the full sequence: streaming reparse, domain customPrompt committed to the repo, custom components with Zod + renderer, CI validation, and MCP exposure for the agent author. Elegance comes from executing the chosen depth well, not from using every package in every app.

Remember: MDMA's whole point is that the packages already solve the hard parts — binding graphs, audit logs, PII redaction, policy, prompt assembly, validation. A good integration trusts them and composes them; a bad integration reinvents them. Compose, don't reinvent.