MDA
MDA Open Spec — a Markdown superset for agent-facing documents. One .mda source compiles to drop-in SKILL.md, AGENTS.md, MCP-SERVER.md, and CLAUDE.md. JSON Schema validated, with typed dependency graph, footnote relationships, and Sigstore-anchored s
What is MDA?
MDA is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to mda open spec — a markdown superset for agent-facing documents. one .mda source compiles to drop-in skill.md, agents.md, mcp-server.md, and claude.md. json schema validated, with typed dependency grap...
MDA Open Spec — a Markdown superset for agent-facing documents. One .mda source compiles to drop-in SKILL.md, AGENTS.md, MCP-SERVER.md, and CLAUDE.md. JSON Schema validated, with typed dependency graph, footnote relationships, and Sigstore-anchored s
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- MDA Open Spec — a Markdown superset for agent-facing documen
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx mdaConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use MDA
MDA (Markdown for Agents) is an open specification and CLI tool that defines a Markdown superset for authoring agent-facing documents, then compiles a single .mda source file into multiple target formats: SKILL.md, AGENTS.md, MCP-SERVER.md, and CLAUDE.md. It adds structured YAML frontmatter with JSON Schema 2020-12 validation, typed dependency graphs, footnote relationships (parent, child, cites, contradicts, extends), and Sigstore-anchored signatures for tamper-evident provenance. AI engineers and teams managing multiple agent runtimes use it to maintain a single source of truth for agent capabilities instead of manually syncing separate files for each framework.
Prerequisites
- Node.js 18+ and npm
- The @markdown-ai/cli package (v1.0.0-rc.3 or later)
- A dbt project or agent skill to document (no external API keys required)
- Basic familiarity with YAML frontmatter and Markdown
- Claude Desktop or another MCP client if using the MCP server integration
Install the MDA CLI
Install the @markdown-ai/cli package globally from npm to get the mda command.
npm install -g @markdown-ai/cliCreate a minimal .mda source file
Author a .mda file with the required YAML frontmatter including a unique doc-id, version, name, and description. The body is standard Markdown.
---
name: pdf-tools
description: Extract PDF text, fill forms, merge files.
metadata:
mda:
doc-id: 38f5a922-81b2-4f1a-8d8c-3a5be4ea7511
version: "1.2.0"
---
# PDF Tools
Tools for working with PDF documents.Validate the .mda file
Run the MDA CLI to validate the file against the JSON Schema 2020-12 conformance suite before compiling.
mda validate pdf-tools.mdaCompile to target formats
Compile the .mda source into one or more target agent document formats. Use --target to specify which format to generate.
mda compile pdf-tools.mda --target SKILL.md
mda compile pdf-tools.mda --target CLAUDE.md
mda compile pdf-tools.mda --target AGENTS.mdConfigure Claude Desktop to use the MDA MCP server
Add the MDA MCP server to your Claude Desktop configuration so Claude can compile and validate .mda files on demand.
{
"mcpServers": {
"mda": {
"command": "npx",
"args": ["mda"]
}
}
}MDA Examples
Client configuration
Claude Desktop JSON configuration for the MDA MCP server.
{
"mcpServers": {
"mda": {
"command": "npx",
"args": ["mda"]
}
}
}Prompts to try
Sample prompts for compiling, validating, and working with MDA agent documents.
- "Compile my web-scraper.mda file into SKILL.md and CLAUDE.md formats"
- "Validate all .mda files in the skills/ directory and list any schema errors"
- "Create a new .mda file for a tool that searches GitHub repositories — include the required frontmatter"
- "Show the dependency graph for my agents based on the 'requires' fields in their .mda files"
- "Generate a SKILL.md from my existing CLAUDE.md by inferring the structure"Troubleshooting MDA
Validation fails with 'doc-id must be a valid UUID' error
The metadata.mda.doc-id field must be a properly formatted UUID v4. Generate one with 'node -e "console.log(crypto.randomUUID())"' or use uuidgen on macOS/Linux and paste it into your frontmatter.
Compilation produces an empty or malformed output file
Ensure the YAML frontmatter is valid and does not contain tab characters (YAML requires spaces for indentation). Run 'mda validate' first — it reports schema violations before compilation runs.
mda command not found after installing @markdown-ai/cli
Global npm packages may not be on your PATH. Run 'npm bin -g' to find the global bin directory and add it to your PATH, or use 'npx @markdown-ai/cli compile ...' as an alternative to the global mda command.
Frequently Asked Questions about MDA
What is MDA?
MDA is a Model Context Protocol (MCP) server that mda open spec — a markdown superset for agent-facing documents. one .mda source compiles to drop-in skill.md, agents.md, mcp-server.md, and claude.md. json schema validated, with typed dependency graph, footnote relationships, and sigstore-anchored s It connects AI assistants to external tools and data sources through a standardized interface.
How do I install MDA?
Follow the installation instructions on the MDA GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with MDA?
MDA works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is MDA free to use?
Yes, MDA is open source and available under the Apache-2.0 license. You can use it freely in both personal and commercial projects.
MDA Alternatives — Similar Developer Tools Servers
Looking for alternatives to MDA? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up MDA in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use MDA?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.