TheDecipherist/markdownai: MarkdownAI - live documents powered by directives

MarkdownAI - live documents powered by directives

Summary

MarkdownAI is a phase-aware workflow engine that turns markdown files containing @-prefixed directives into renderable runbooks for AI agents. The engine executes directives for database queries, file operations, and control flow inline with prose, then ships the agent only the context it needs for the current step. Version 2 unifies the directive grammar, adds synchronous MongoDB support, reusable partials, and a Model Context Protocol (MCP) server for direct integration with assistants.

What it is useful for

Engineers building agentic workflows can use MarkdownAI to script multi-step procedures where each phase pulls only the data the agent needs. A document can query MongoDB with @db, run tests via @test, gate phases on conditions with @if, and inline other documents with @template, all without leaving markdown. The MCP package exposes 11 tools so assistants like Claude can render a document through mcp__markdownai__render and receive a fully resolved view.

It is also useful for keeping AI agents grounded in real project structure. Framework descriptors such as mdd.plugin.md declare project layout, so the engine reads layout facts from the descriptor rather than guessing. Sandbox builtins like parse_brief, extract_paths, now_iso, and uuid_v4 work inside @if conditions and {{ }} interpolations.

How engineers can use it

The README documents a short quickstart. Install the CLI and render a sample:

npm install -g @markdownai/core
mai render hello.md

A hello.md example combines a database count with a conditional:

@markdownai v2.0

# Project status

Database has @count using="local" find="users" / users right now.

@if {{ env.NODE_ENV == "production" }}
  Running in production mode.
@if-end

The monorepo is split into five packages: @markdownai/parser (grammar and AST), @markdownai/engine (executor), @markdownai/renderer (output formatters), @markdownai/mcp (MCP server), and @markdownai/core (the mai CLI). A VS Code extension called markdownai adds syntax highlighting and diagnostics for files beginning with @markdownai.

Teams on v1 should note that v2 is a breaking syntax change. Bare @end, @endif, and @endswitch are no longer accepted, and the close tag must carry the directive name. The README provides an idempotent migration script for converting v1 files. Security defaults are restrictive: shell access starts read-only with common test runners, HTTP is off, and DB is off, so enabling features like MongoDB or broader shell commands requires editing ~/.markdownai/security.json. The project requires Node.js 18 or newer and is MIT-licensed.