Markdown Rules

What is Markdown Rules?

Markdown Rules is an MCP server that organizes project documentation into structured context for AI coding tools like Cursor. It uses YAML frontmatter in Markdown files to define how each document is included in AI conversations.

How to use Markdown Rules?

Install globally with npm install -g @valstro/markdown-rules-mcp, then configure the MCP server with PROJECT_ROOT, MARKDOWN_INCLUDE, and optional HOIST_CONTEXT environment variables. Create .md files with YAML frontmatter and invoke get_relevant_docs to fetch relevant documentation.

Key features of Markdown Rules

• Define document inclusion types via YAML frontmatter (global, auto-attached, agent-requested, manual)
• Link to external files and embed specific line ranges from code/config files
• Hoist linked file context for improved AI awareness
• Reindex documentation when files change
• Customizable usage instructions for the AI assistant

Use cases of Markdown Rules

• Provide project-wide guidelines that the AI always sees (e.g., coding standards)
• Auto-attach documentation when certain file types are attached (e.g., TypeScript rules when .ts files are added)
• Let the AI dynamically select relevant docs based on the user's query
• Manually include specific documentation with the @ symbol for ad‑hoc needs

FAQ from Markdown Rules

What environments does Markdown Rules require?

Node.js v18 or higher and an MCP‑supported AI coding tool like Cursor.

How are documents classified for inclusion?

Via YAML frontmatter: alwaysApply: true for global, globs list for auto‑attached, a description for agent‑requested, or no frontmatter for manual inclusion.

Can I override the default usage instructions for the AI?

Yes. Create a markdown-rules.md file in your project root. The path can also be customized via the USAGE_INSTRUCTIONS_PATH environment variable.

Does Markdown Rules support linking to code or configuration files?

Yes. Append ?md-link=true to include the full file, or ?md-embed=START-END to embed specific line ranges inline.

What is the default exclude pattern for documentation files?

By default, Markdown Rules excludes **/node_modules/**,**/build/**,**/dist/**,**/.git/**,**/coverage/**,**/.next/**,**/.nuxt/**,**/out/**,**/.cache/**,**/tmp/**,**/temp/**.