MDMA

At a Glance:

MDMA (Markdown Document with Mounted Applications) is an open-source specification and TypeScript toolkit that extends Markdown with interactive components — such as forms, tables, and approval gates — that LLMs can generate for structured, inline user interaction in AI-powered applications.

Overview:

MDMA is a specification and developer toolkit that extends standard Markdown with interactive component blocks defined in fenced mdma code blocks, turning static documents into actionable applications. It addresses the limitation of text-only AI conversations by providing a predictable schema for LLMs to generate structured, validated components that frontends can render without custom UI per use case. The project provides a TypeScript monorepo including a parser, headless runtime for reactive state management, React rendering layer, LLM system prompts for model-optimized authoring, a static analysis validator with auto-fix capabilities, and an MCP server for AI assistant integration. It is suitable for developers building AI-driven applications that require structured data collection, workflow approvals, or interactive data displays inline within chat or document interfaces.

Key Decision Points:

• Specification-first approach: MDMA defines a formal component specification with Zod schemas and TypeScript types, ensuring all generated components are structurally validated before rendering.

• Multiple integration paths: The project provides parser/runtime packages for direct integration, a React renderer for visual output, system prompts for LLM-based generation, and an MCP server for AI assistant tooling.

• Built-in data protection: The runtime engine includes automatic PII redaction (hash, mask, omit) and an append-only, tamper-evident audit log with hash chaining.

• Multi-model prompt support: The prompt pack ships model-specialized authoring variants for OpenAI, Anthropic, Google, and xAI models, with documented pass rates across evaluation suites.

• Static analysis with auto-fix: The validator applies 17 lint rules and 6 auto-fix strategies to catch common LLM mistakes, including YAML errors, ID collisions, and PII flag omissions.

• Packaged as a monorepo: The system is distributed across 10 scoped packages under @mobile-reality, allowing developers to install only the components needed for their use case.

Core Features:

• Fenced MDMA component blocks: Interactive components (form, table, button, tasklist, callout, approval-gate, chart, thinking, webhook) defined in fenced mdma code blocks within Markdown, using YAML syntax.

• Reactive document store: A headless state management engine that manages reactive bindings between components, dispatches typed actions, enforces environment-based allow/deny policies, and writes events to an audit log with automatic PII redaction.

• Model-optimized prompt pack: Pre-tuned system prompts for LLMs to author valid MDMA documents, with per-model variants selectable via getAuthorPromptVariant(modelId) and support for layering domain-specific custom instructions.

• 17-rule static analysis validator: Validates YAML correctness, schema conformance, ID uniqueness, binding syntax, action references, PII sensitivity flags, flow ordering, and expected component presence, with fuzzy suggestions and auto-fix strategies.

• MCP server for AI assistants: Exposes MDMA spec, prompt variants, package information, and validation tools to MCP-compatible clients like Claude Desktop, VS Code, and Cursor through structured tool calls.

• Interactive prompt builder CLI: A local web-based tool for visually selecting components, configuring fields, setting domain rules and trigger conditions, then generating a tailored customPrompt for use in LLM-based generation.

Use Cases:

• AI-driven form collection: Developers can build applications where LLMs respond with structured forms for data intake (e.g., patient registration, bug reports) instead of free-text questions, with automatic PII detection and audit logging.

• Multi-step approval workflows: Using approval-gate components, developers can create document-based workflows where users approve or deny steps inline, with the runtime enforcing forward-only action references and no circular dependencies.

• AI assistant integration via MCP: Developers can expose MDMA capabilities to coding agents so they can discover packages, retrieve spec definitions, generate prompts, and validate documents without reading source code or documentation manually.

• CI/CD document validation: The validator package supports static analysis in CI pipelines, checking that MDMA documents meet structural rules and automatically fixing common LLM output errors like ID collisions and kebab-case violations.

Open-Source Alternative Value:

MDMA provides an open-source specification and implementation for structured, interactive LLM outputs, offering a deterministic parsing approach based on Markdown and YAML rather than runtime JavaScript. Developers can self-host or embed the parsing, runtime, and rendering components, maintaining control over document state and audit data. The project includes an append-only audit log with tamper-evident hashing and a policy engine that enforces allow/deny rules per action and environment, giving developers explicit control over what components can execute in production. The pluggable rendering layer supports custom component implementations, and the modular package architecture allows selective adoption without pulling in unnecessary dependencies.