io.github.MobileReality/mdma

Why MDMA?

AI conversations today are plain text — the user reads a response and manually acts on it. MDMA changes that. When an LLM knows the MDMA spec, it can respond with interactive components (forms, tables, approval gates) instead of just text. The conversation becomes actionable: the user fills out a form, approves a step, or reviews structured data — all inline, with a predictable schema that your app already knows how to render and process.

No custom UI per use case. No parsing free-form text. The AI generates structured, validated components and your frontend renders them instantly.

What is MDMA?

MDMA extends Markdown with interactive components defined in fenced mdma code blocks. A regular Markdown file becomes an interactive application:

# Patient Intake

```mdma
type: form
id: intake-form
fields:
  - name: patient-name
    type: text
    label: "Full Name"
    required: true
    sensitive: true
  - name: email
    type: email
    label: "Email"
    required: true
    sensitive: true
  - name: reason
    type: textarea
    label: "Reason for Visit"
    required: true
```

```mdma
type: button
id: submit-btn
text: "Submit Intake Form"
variant: primary
onAction: submit
```

MDMA_AUTHOR prompt matrix

Each cell shows the pass rate of the model-specialized MDMA_AUTHOR prompt variant on the listed eval suite.

✅ 100% on the suite.

🟡 Scoring between 80–99% on the suite.

🔴 Scoring below 80% on the suite.

Don't see your model? Add a prompt variant under packages/prompt-pack/src/prompts/mdma-author/<vendor>/ and open a PR — we'll run the eval suite and add it to this table.

† gpt-5.4 intermittent duplication bug — gpt-5.4 passes one-shot evals reliably but shows a non-deterministic output duplication in multi-turn, custom-prompt, and flow evals (~7–15% of runs). The model generates a complete, correct response and then immediately re-emits the entire output verbatim, causing [duplicate-ids] validation errors. This is a known model-level issue unrelated to the prompt variant. See the OpenAI community thread for details. If this affects your use case, prefer gpt-5.5 or gpt-5.2.

‡ gemini-3.1-pro-preview stochastic preamble loop — on ~7–15% of flow-eval runs, the model emits a chain-of-thought as visible Markdown prose (e.g. **Investigating Production Errors** repeated 3–5 times) instead of opening a ```mdma block, producing either [yaml-correctness: outside fenced block] or [duplicate-ids] errors. Per Google's official Gemini 3 prompting guide, this is a model-level behavior driven by temperature/sampling — prompt-level fixes shift which test loops rather than eliminating the loops. If deterministic flow output matters, prefer gemini-2.5-pro for production multi-step flows.

* Smaller / lower-tier models from any lab (OpenAI mini · nano, Anthropic Haiku, Google Gemini Flash, etc.) pass our eval suites, which exercise short, structured test cases. In longer real-world conversations they tend to hallucinate, forget earlier turns, or drift from the spec. For production use that involves multi-turn dialogue or stateful flows, prefer the flagship-tier model from the same family.

[i] Noticeably slow response times — single-turn responses commonly take tens of seconds and full eval runs measure in minutes.

MDMA_FIXER prompt matrix

Each cell shows the pass rate of the model-specialized MDMA_FIXER prompt variant on the single-block fixer eval (15 tests covering structural fixes, bindings, PII, forms, tables/charts, approvals). The fixer is what powers automatic repair of LLM output that fails validate() — every supported model lands at ✅ via model-tailored inline guards (no-leading-separator, preserve-input-structure, table-key-direction, replace-all-placeholders, fix-all-listed-errors, etc.).

✅ 100% on the single-block fixer eval (15/15).

‡ Reasoning-token leak suppression — for reasoning-flavoured Gemini Pro variants and Grok 4.3, the fixer would otherwise see visible "Thinking: Topic" prose prepended to every response. The eval config sets passthrough.reasoning.exclude: true (and the demo's usePreviewValidation does the same per-provider) to strip reasoning tokens from the response body at the API layer rather than at the prompt layer.

Components

9 built-in component types, all rendered out of the box by @mobile-reality/mdma-renderer-react:

Additionally, standard Markdown content (headings, paragraphs, lists, code blocks, images, links, tables, etc.) is rendered inline between components.

Custom Chart Renderer

The built-in chart renderer intentionally renders data as a plain table so the library stays lightweight. To get actual charts, register a custom renderer:

import { MdmaDocument } from '@mobile-reality/mdma-renderer-react';
import { MyRechartsRenderer } from './MyRechartsRenderer';

function App({ ast, store }) {
  return (
    <MdmaDocument
      ast={ast}
      store={store}
      customizations={{
        components: {
          chart: MyRechartsRenderer,
        },
      }}
    />
  );
}

This pattern works for overriding any built-in component — pass a custom React component under customizations.components.<type>.

Installation

# Core — parse and run MDMA documents
npm install @mobile-reality/mdma-parser @mobile-reality/mdma-runtime

# React rendering
npm install @mobile-reality/mdma-renderer-react

# AI authoring — system prompts for LLM-based generation
npm install @mobile-reality/mdma-prompt-pack

# Validation — static analysis for MDMA documents
npm install @mobile-reality/mdma-validator

# CLI — interactive prompt builder + document validation
npx @mobile-reality/mdma-cli

All packages are published under the @mobile-reality npm org.

Usage

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import { remarkMdma } from '@mobile-reality/mdma-parser';
import { createDocumentStore } from '@mobile-reality/mdma-runtime';
import type { MdmaRoot } from '@mobile-reality/mdma-spec';

// 1. Parse markdown into AST
const processor = unified().use(remarkParse).use(remarkMdma);
const tree = processor.parse(markdown);
const ast = (await processor.run(tree)) as MdmaRoot;

// 2. Create a reactive document store
const store = createDocumentStore(ast, {
  documentId: 'my-doc',
  sessionId: crypto.randomUUID(),
});

// 3. Subscribe to state changes
store.subscribe((state) => {
  console.log('Bindings:', state.bindings);
});

// 4. Dispatch user actions
store.dispatch({
  type: 'FIELD_CHANGED',
  componentId: 'intake-form',
  field: 'patient-name',
  value: 'Jane Doe',
});

In a Chat

import { buildSystemPrompt, getAuthorPromptVariant } from '@mobile-reality/mdma-prompt-pack';

// Pick the prompt variant tuned for your model (falls back to default if unknown)
const { prompt: authorPrompt } = getAuthorPromptVariant('google/gemini-2.5-pro');

// Optionally layer a custom prompt on top for domain-specific generation
const systemPrompt = buildSystemPrompt({
  authorPrompt,
  customPrompt: `You are a bug tracking assistant. When a user reports a bug,
always generate a single form component matching this exact structure:

\`\`\`mdma
type: form
id: bug-report
fields:
  - name: title
    type: text
    label: "Bug Title"
    required: true
  - name: severity
    type: select
    label: "Severity"
    options:
      - { label: Critical, value: critical }
      - { label: High, value: high }
      - { label: Medium, value: medium }
      - { label: Low, value: low }
  - name: steps
    type: textarea
    label: "Steps to Reproduce"
    required: true
  - name: expected
    type: textarea
    label: "Expected Behavior"
  - name: actual
    type: textarea
    label: "Actual Behavior"
\`\`\``,
});

// Send to any OpenAI-compatible API
const response = await fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({
    model: 'gemini-2.5-pro',
    messages: [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: 'The login page crashes after entering my password.' },
    ],
  }),
});

// The LLM responds with regular markdown containing ```mdma blocks
// Parse it into an AST + store as shown above

React

import { MdmaDocument } from '@mobile-reality/mdma-renderer-react';
import '@mobile-reality/mdma-renderer-react/styles.css'; // default styles

function App({ ast, store }) {
  return <MdmaDocument ast={ast} store={store} />;
}

Note: The styles.css import provides default styling for all MDMA components (forms, tables, callouts, animations, etc.). It's optional — you can write your own styles targeting the .mdma-* CSS classes instead.

Packages

Architecture

@mobile-reality/mdma-spec                  Format specification + Zod schemas
  ├── @mobile-reality/mdma-parser          Markdown → MDMA AST (remark plugin)
  ├── @mobile-reality/mdma-prompt-pack     AI authoring prompts
  ├── @mobile-reality/mdma-validator       Document validation
  └── @mobile-reality/mdma-runtime         State / events / policy engine
        └── @mobile-reality/mdma-attachables-core   Component handlers
              └── @mobile-reality/mdma-renderer-react   React components
@mobile-reality/mdma-cli                   CLI prompt builder + validation
@mobile-reality/mdma-mcp                   MCP server for AI assistants
@mobile-reality/mdma-evals                 LLM evaluation suite (promptfoo)

Getting Started

pnpm install
pnpm build
pnpm test

CLI

Interactive prompt builder for creating custom MDMA prompts.

# Run the prompt builder — opens a web app in your browser
npx @mobile-reality/mdma-cli

# Validate MDMA documents
npx @mobile-reality/mdma-cli validate "docs/**/*.md"
npx @mobile-reality/mdma-cli validate "docs/**/*.md" --fix  # auto-fix issues
npx @mobile-reality/mdma-cli validate "docs/**/*.md" --json # JSON output

The prompt builder walks you through:

1. Pick components — select from the 9 MDMA types (form, table, approval-gate, etc.)
2. Configure — define fields, options, roles, sensitive flags, and business rules
3. Set triggers — specify when the AI should generate MDMA components (keywords, contextual conditions)
4. Generate — an LLM creates a tailored customPrompt based on your configuration
5. Export — copy the result and use it in your app:

import { buildSystemPrompt } from '@mobile-reality/mdma-prompt-pack';

const systemPrompt = buildSystemPrompt({
  customPrompt: '<paste generated prompt here>',
});

Validator

Static analysis engine for MDMA documents. Validates structure, catches common LLM mistakes, and auto-fixes what it can.

import { validate } from '@mobile-reality/mdma-validator';

const result = validate(markdown);
// result.ok        — true if no unfixed errors
// result.issues    — all issues found
// result.output    — auto-fixed markdown
// result.fixCount  — number of issues auto-fixed

Rules

Every rule can be individually disabled via the exclude option:

const result = validate(markdown, {
  exclude: ['thinking-block', 'placeholder-content'],
});

Auto-fix Pipeline

When autoFix: true (default), 6 fix strategies run in strict dependency order:

1. id-format — normalize IDs to kebab-case, update all cross-references
2. duplicate-ids — deduplicate after normalization
3. binding-syntax — fix {x} -> {{x}}, strip whitespace
4. sensitive-flags — add sensitive: true to PII fields
5. action-references — remove invalid references
6. schema-conformance — patch missing labels/headers/content, infer field types, wrap bare bindings, re-validate with Zod

Expected Components

When you need to guarantee that the LLM generates specific critical components for the user (e.g. a form with required fields, a table with specific columns), pass their expected shapes to the validator. The rule only validates components that are actually present in the current message — components not found are silently skipped. This makes it safe to pass the full set of expected components across a multi-turn flow:

// Define all expected components once (e.g. from a blueprint or flow definition)
const expectedComponents = {
  'contact-form': {
    type: 'form',
    fields: ['email', 'phone', 'full-name'],
  },
  'approval-gate': { type: 'approval-gate' },
  'submit-btn': { type: 'button' },
};

// Pass the same set to every message — the rule checks only what's present
const result = validate(message1, { expectedComponents });
// Message 1 contains contact-form → validates type + fields
// approval-gate and submit-btn not in this message → skipped

const result2 = validate(message2, { expectedComponents });
// Message 2 contains approval-gate → validates type
// contact-form and submit-btn not in this message → skipped

For each component found in the message, the rule checks:

• Is the type correct?
• Are all expected form fields present? (lists available fields on mismatch)
• Are all expected table columns present? (lists available columns on mismatch)

LLM Error Recovery

The parser handles three common LLM mistakes automatically during block extraction:

• Colon-space in values — label: Step 1: Enter info auto-quoted to label: "Step 1: Enter info"
• YAML --- separators — stripped before parsing
• Multiple components in one block — split at each root-level type: line into separate blocks

MCP Server

MCP (Model Context Protocol) server that lets AI assistants understand and work with MDMA.

Setup

Add to your AI tool config (Claude Desktop, VS Code, Cursor, etc.):

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

Tools

Example: Building a prompt with structured input

An AI agent calls build-system-prompt with:

{
  "domain": "HR onboarding",
  "components": ["form", "approval-gate", "webhook"],
  "fields": [
    { "name": "email", "type": "email", "sensitive": true, "required": true },
    { "name": "department", "type": "select", "options": ["Engineering", "Marketing"] }
  ],
  "steps": [
    { "label": "Registration", "description": "Employee fills in personal details" },
    { "label": "Approval", "description": "Manager reviews and approves" }
  ],
  "businessRules": "All PII fields must be marked sensitive."
}

The tool returns a structured custom prompt ready to use with buildSystemPrompt({ customPrompt }).

Testing locally

npx @modelcontextprotocol/inspector node packages/mcp/dist/bin/mdma-mcp.js

MCP vs No-MCP: Agent Implementation Comparison

We tested building the same MDMA chat app with two AI agents — one with the MCP server enabled, one without. Here's what happened:

Key takeaway: The MCP server eliminated the discovery phase entirely. Instead of the agent reading source code to understand MDMA, it called 3 tools (list-packages → get-spec → get-prompt) and had complete, structured knowledge of the ecosystem within seconds.

Skills

Agent-authoring guidance packaged as a portable Agent Skill (compatible with Claude Code, the Agent SDK, and any harness that consumes SKILL.md).

The skill is intentionally portable: every code sample is inline and every reference uses @mobile-reality/mdma-* package names, so it works when dropped into a project that only installs the published packages. Drop the folder into .claude/skills/ (Claude Code), your Agent SDK skills directory, or any compatible location.

Paired with the MCP server, an agent gets both how to think about the integration (skill) and live access to spec, prompts, and docs (MCP tools) — the skill tells it to call buildSystemPrompt / validate / updateAst, and the MCP tools give it the actual spec and docs to do so correctly.

Evals

LLM evaluation suite using promptfoo to verify MDMA generation quality.

# Run base eval suite (25 tests)
pnpm eval

# Run custom system prompt tests (10 tests)
pnpm eval:custom

# Run multi-turn conversation tests (25 turns across 11 conversations)
pnpm eval:conversation

# Run prompt builder tests (25 tests)
pnpm eval:prompt-builder

# Run all eval suites
pnpm eval:all

# View results in browser
pnpm eval:view

Key Features

• Deterministic parsing — Markdown + YAML, no runtime JS in documents
• PII protection — Automatic detection + redaction (hash, mask, omit)
• Audit trail — Append-only event log with tamper-evident hash chaining
• Policy engine — Allow/deny rules per action and environment
• AI authoring — System prompts for AI-assisted document creation

Initial Roadmap

v0.2 — Developer Experience

• More examples (14 real-world use cases)
• CLI tool for prompt creation (MDMA flows)
• Improved validator
• Added MCP
• Added Skills for Agentic usage
• Improved error messages in parser
• File upload field type for forms

v0.3 — AI & Generation

• Multi-model eval coverage (Claude, GPT, Gemini, Grok)
• Prompt tuning toolkit — test and compare custom prompts
• Agent-friendly SDK — let AI agent generate your MDMA
• Validator tests & Fixer evals
• Integrations
• Webhook execution engine (real HTTP calls in production environments)

v1.0 — Production Ready

• Stable API with semantic versioning guarantees
• E2E test suite for full document workflows
• Performance benchmarks and optimization
• Migration guides between versions
• Blueprints promoted from experimental to stable

Future

• Collaborative editing (multiplayer document state)
• Custom component marketplace
• Audit trail dashboard UI
• HIPAA / SOC 2 compliance documentation

Tech Stack

TypeScript monorepo — pnpm workspaces, Turborepo, Zod, React, Vitest, remark

Built by Mobile Reality

MDMA is built and maintained by Mobile Reality — an AI automation agency specializing in AI agent development, custom software, and enterprise automation. We use MDMA in production across fintech and proptech projects.

Read more:

• LLM Interface: The Missing Layer Between Your AI Model and Your Users
• Structured LLM Output Without JSON Schemas
• Generative UI: How AI Creates Dynamic User Interfaces

License

MIT