MDMA (Markdown Document with Mounted Applications) extends Markdown with interactive components defined in fenced mdma code blocks. A regular Markdown file becomes an interactive application with forms, tables, charts, approval gates and more.

How is MDMA different from raw markdown or a JSON UI contract?

Raw Markdown renders as text and a custom JSON UI contract is brittle on smaller models. MDMA is forgiving Markdown that small, cheap models emit reliably, and it is schema-validated so the output is renderable and safe.

Why does MDMA save on tokens?

Because MDMA works on small, cheap models such as Gemini Flash and Claude Haiku where strict JSON often breaks. A deterministic validator and an LLM fixer keep the loop cheap, so you don't burn tokens re-asking a large model to repair its own output.

Which packages does MDMA ship?

The core packages are @mobile-reality/mdma-parser, @mobile-reality/mdma-validator, @mobile-reality/mdma-runtime and @mobile-reality/mdma-renderer-react, plus a prompt-pack, CLI and MCP server.

Yes. MDMA is MIT-licensed and maintained by Mobile Reality. The source is on GitHub at github.com/MobileReality/mdma.

Does MDMA work with Claude, GPT and Gemini?

Yes. MDMA is model-agnostic: any LLM that can write Markdown can emit MDMA. Because the format is forgiving, it works on small, cheap models such as Gemini Flash and Claude Haiku, not only the largest tiers. A prompt-pack and MCP server help LLMs produce valid MDMA.

How do I render MDMA in React?

Install @mobile-reality/mdma-renderer-react along with the parser and runtime, parse the markdown to an AST, create a document store, and pass them to the MdmaDocument component. It renders every component type as a live, stateful element.

Generative UI for LLMs · open source by Mobile Reality

MDMA: Markdown that mountsreal applications.

MDMA extends Markdown with interactive components defined in fenced ```mdma blocks. Give an LLM the spec and it returns structured, validated, renderable UI (forms, tables, approval gates) instead of a wall of text.

Get started View on GitHub

$ npm install @mobile-reality/mdma-renderer-react

Parse → validate → run → render

Four small packages take a markdown file the whole way to a live, stateful interface. Use the ones you need.

Parser

@mobile-reality/mdma-parser

Remark plugin: Markdown → MDMA AST.

Validator

@mobile-reality/mdma-validator

Static analysis, lint rules, auto-fix.

Runtime

@mobile-reality/mdma-runtime

State, bindings, audit log, policies.

Renderer

@mobile-reality/mdma-renderer-react

React components for every block type.

Nine component types

MDMA defines nine interactive component types: form, button, tasklist, table, callout, approval-gate, webhook, chart, and thinking. Each is a schema in the spec. Write its short YAML in an ```mdma block and the renderer turns it into a live, stateful element in React.

type: form

Typed fields, validation, sensitive flags.

type: button

Actions with optional confirm dialogs.

type: tasklist

Checklists with required items + onComplete.

type: table

Sortable columns over structured rows.

type: callout

Info / warning / error notices.

type: approval-gate

Role-based sign-off before proceeding.

type: webhook

Fire an outbound call on an event.

type: chart

Line / bar visualisations from inline data.

type: thinking

Render the model's reasoning trace.

Edit the markdown. Watch it render.

This is the real @mobile-reality/mdma-renderer-react running in your browser. Change the source on the left.

document.md

rendered output

Parsing…

Talk to the MDMA Agent

Describe a component for your own use case: a contact form, a sortable table, an onboarding checklist, an approval gate. The agent renders it live in the panel on the right. Verify your email to start.

Loading interactive demo…

Same prompt. Different contract.

Ask an LLM to collect contact details. Without a spec you get prose you have to parse by hand. With MDMA you get a block you can render and validate.

Without MDMA: free-form text

Sure! To contact us, please provide the following information:

1. Your full name
2. Your email address
3. A message (at least a few sentences)

Once you've gathered those, you can send them over and
someone from the team will reply. Let me know if you'd
like me to format this as a list or a table instead!

With MDMA: a renderable block

# Contact us

Fill in the form below and we'll get back to you.

```mdma
id: contact-form
type: form
fields:
  - name: full_name
    type: text
    label: Full Name
    required: true
  - name: email
    type: email
    label: Email Address
    required: true
  - name: message
    type: textarea
    label: Message
    required: true
    validation:
      min: 10
      message: Please enter at least 10 characters.
onSubmit: submit-contact
```

```mdma
id: send-btn
type: button
text: Send Message
variant: primary
onAction: submit-contact
```

Built for the token bill

MDMA cuts token cost because it runs on small, cheap models. Strict JSON breaks on those models (one bad quote and the whole payload is unusable), so teams reach for the largest tier. MDMA uses forgiving Markdown that small models like Gemini Flash and Claude Haiku emit reliably, backed by a deterministic validator and an LLM fixer. See it live in the MDMA Agent demo.

Runs on small, cheap models

Markdown is forgiving where strict JSON is brittle. A small model that mangles a JSON quote sends the whole payload to the bin; the same model emits valid MDMA. That means fast, low-cost models like Gemini Flash and Claude Haiku, instead of always reaching for the largest tier.

Deterministic validator, free

MDMA ships a static validator (17 lint rules) that runs without an LLM. Catching structural problems costs nothing per call, so you don't burn tokens re-asking the model to fix its own output.

LLM fixer for the rest

What the validator can't auto-fix goes to a fixer that repairs broken documents, and it works on the same small models, keeping the whole loop cheap.

What we eval

133 test cases · 9 suites · 12 models from Flash & Haiku to Opus

Suite	Tests	What it asserts
Author	28	Correct component, exact field count, PII flags
Conversation	30	No regeneration on follow-up turns
Conversation flow	6	LLM-judged conversation quality
Custom prompt	13	Author + custom system prompt layering
Flows	15	Example flow custom prompts
Guidance	15	Calls the generate_mdma tool correctly
Fixer	15	Repairs broken MDMA to valid output
Prompt builder	10	CLI prompt builder output
Isolated	1	Single failure-case iteration

Models in the eval matrix

OpenAI GPT-5.x / 4.1 (incl. mini, nano)
Claude Opus / Sonnet / Haiku
Gemini 3.1 / 2.5 (incl. Flash, Flash-Lite)
xAI Grok 4.x

The eval suites run across all of these models; the same suites pass on the small, cheap tiers, not only the large ones. Run them yourself with the PromptFoo configs in mdma/evals.

Real use cases, shipped in the repo

Every example below is a working MDMA document in the open-source project, from a one-field form to a dual-approval compliance flow, built from the nine component types.

Examples

common use cases

Contact form

Collect a name, email and message, then submit. The simplest MDMA document.

formbutton

Budget approval

Submit a budget request, complete prerequisites, and gate it behind manager sign-off.

formtasklistapproval-gatecallout

Employee onboarding

Welcome a new hire through personal info, equipment selection and a manager checklist.

formtasklistapproval-gatecallout

Bug report

Capture reproduction steps and severity, with a triage checklist before submission.

formtasklistbuttoncallout

Customer survey

Structured post-support feedback with ratings, checkboxes and optional follow-up.

formcalloutbutton

Order tracking

Order status, shipment details and delivery milestones at a glance.

tablecharttasklistcallout

Sprint retrospective

Team metrics, feedback and action items captured from the sprint retro.

formcharttasklistcallout

Sales dashboard

Quarterly revenue trends, team breakdown and a sortable deals table.

charttabletasklistcallout

Feature request

A product request with business justification and a product-manager review gate.

formtasklistapproval-gatecallout

Job application

Apply with a resume and optional portfolio. Shows the file-upload field.

formbutton

Try it on GitHub

Browse and run every example in the repo.

Blueprints

industry-specific workflows

Incident triage

Critical Ops

Assess severity, notify stakeholders, track resolution and gate closure behind sign-off.

formtasklistapproval-gatebuttoncallout

Change management

Engineering / Compliance

SOX/ISO release approval: risk assessment, dual approval and a pre-deploy checklist.

formtasklistapproval-gatecallout

Customer escalation

Customer Ops

SLA-aware escalation with sentiment tracking and a dynamic escalation-history table.

formtabletasklistbuttoncallout

Clinical procedure approval

Healthcare

Clinical + QA review and safety verification before a procedure is published.

formtasklistapproval-gatecallout

KYC case review

Finance / Compliance

Identity verification for KYC/AML: PII handling, document table and compliance approval.

formtabletasklistapproval-gate

Try it on GitHub

Open the blueprints folder to inspect or fork them.

Where MDMA fits

Between raw markdown and a hand-built JSON UI contract.

	Raw MD	Custom JSON	MDMA
Renders as interactive UI
Readable as plain text
Schema-validated		partial
LLM emits it reliably		partial
Stateful (bindings, audit)
No front-end build needed

Two ways in

Developers

Parse and run MDMA documents, then render them in React.

$ npm install @mobile-reality/mdma-parser @mobile-reality/mdma-runtime

$ npm install @mobile-reality/mdma-renderer-react

AI authoring

Give an LLM the prompt pack, or build prompts with the CLI.

$ npm install @mobile-reality/mdma-prompt-pack

$ npx @mobile-reality/mdma-cli

Frequently asked questions

What is MDMA?: MDMA (Markdown Document with Mounted Applications) extends Markdown with interactive components defined in fenced mdma code blocks. A regular Markdown file becomes an interactive application with forms, tables, charts, approval gates and more.
How is MDMA different from raw markdown or a JSON UI contract?: Raw Markdown renders as text and a custom JSON UI contract is brittle on smaller models. MDMA is forgiving Markdown that small, cheap models emit reliably, and it is schema-validated so the output is renderable and safe.
Why does MDMA save on tokens?: Because MDMA works on small, cheap models such as Gemini Flash and Claude Haiku where strict JSON often breaks. A deterministic validator and an LLM fixer keep the loop cheap, so you don't burn tokens re-asking a large model to repair its own output.
Which packages does MDMA ship?: The core packages are @mobile-reality/mdma-parser, @mobile-reality/mdma-validator, @mobile-reality/mdma-runtime and @mobile-reality/mdma-renderer-react, plus a prompt-pack, CLI and MCP server.
Is MDMA open source?: Yes. MDMA is MIT-licensed and maintained by Mobile Reality. The source is on GitHub at github.com/MobileReality/mdma.
Does MDMA work with Claude, GPT and Gemini?: Yes. MDMA is model-agnostic: any LLM that can write Markdown can emit MDMA. Because the format is forgiving, it works on small, cheap models such as Gemini Flash and Claude Haiku, not only the largest tiers. A prompt-pack and MCP server help LLMs produce valid MDMA.
How do I render MDMA in React?: Install @mobile-reality/mdma-renderer-react along with the parser and runtime, parse the markdown to an AST, create a document store, and pass them to the MdmaDocument component. It renders every component type as a live, stateful element.