Markdown Rules

Prerequisites 📋

• Node.js (v18 or higher)
• Cursor or other MCP supported AI coding tools

Installation 🛠️

Manual Installation

1. Install the MCP server

npm install -g @valstro/markdown-rules-mcp

2. Configure the MCP server

{
  "mcpServers": {
    "markdown-rules-mcp": {
      "command": "npx",
      "args": ["-y", "@valstro/markdown-rules-mcp"],
      "env": {
        "PROJECT_ROOT": "/absolute/path/to/project/root",
        "MARKDOWN_INCLUDE": "./docs/**/*.md",
        "HOIST_CONTEXT": true
      }
    }
  }
}

Configuring Usage Instructions (Optional)

To change the default usage instructions, create a markdown-rules.md file in your project root. The file should contain the usage instructions for the get_relevant_docs tool.

The default usage instructions are:

# Usage Instructions

*   You **must** call the `get_relevant_docs` MCP tool before providing your first response in any new chat session.
*   After the initial call in a chat, you should **only** call `get_relevant_docs` again if one of these specific situations occurs:
    *   The user explicitly requests it.
    *   The user attaches new files.
    *   The user's query introduces a completely new topic unrelated to the previous discussion.

Note: You can change the default usage instructions file path by adding the USAGE_INSTRUCTIONS_PATH environment variable to the MCP server configuration.

Tools

• get_relevant_docs - Get relevant docs based on the user's query. Is called based on the usage instructions.
• list_indexed_docs - Count and preview indexed docs & usage instructions. Useful for debugging.
• reindex_docs - Reindex the docs. Useful if docs in the index have changed or new docs have been added.

How To Use 📝

Create .md files in your project with YAML frontmatter to define how they should be included in AI context.

Document Types

Frontmatter Examples

Global (always included):

---
description: Project Guidelines
alwaysApply: true
---
# Project Guidelines

This doc will always be included.

Auto-attached (included when TypeScript files are attached):

---
description: TypeScript Coding Standards
globs: ["**/*.ts", "**/*.tsx"]
---
# TypeScript Coding Standards

This doc will be included when TypeScript files are attached.

Agent-requested (available for AI to select based on relevance):

---
description: Database Schema and Migration Guide
---
# Database Schema and Migration Guide

This doc will be included when AI selects it based on relevance.

No frontmatter (must be included in the prompt manually with @ symbol):

# Testing Guidelines

This doc needs manual inclusion with @ symbol

Linking Files

Link other files: Add ?md-link=true to include linked files in context

See [utilities](./src/utils.ts?md-link=true) for helper functions.

Embed specific lines: Add ?md-embed=START-END to include only specific lines inline

Configuration: [API Settings](./config.json?md-embed=1-10)

Configuration

• PROJECT_ROOT - Default: process.cwd() - The absolute path to the project root.
• MARKDOWN_INCLUDE - Default: **/*.md - Pattern to find markdown doc files
• HOIST_CONTEXT - Default: true - Whether to show linked files before the docs that reference them
• MARKDOWN_EXCLUDE - Default: **/node_modules/**,**/build/**,**/dist/**,**/.git/**,**/coverage/**,**/.next/**,**/.nuxt/**,**/out/**,**/.cache/**,**/tmp/**,**/temp/** - Patterns to ignore when finding markdown files

Example 📝

Imagine you have the following files in your project:

project-overview.md:

---
description: Project Overview and Setup
alwaysApply: true
---
# Project Overview

This document covers the main goals and setup instructions.

See the [Core Utilities](./src/utils.ts?md-link=true) for essential functions.

For configuration details, refer to this section: [Config Example](./config.json?md-embed=1-3)

src/utils.ts:

// src/utils.ts
export function helperA() {
  console.log("Helper A");
}

export function helperB() {
  console.log("Helper B");
}

config.json:

{
  "timeout": 5000,
  "repeats": 3,
  "retries": 3,
  "featureFlags": {
    "newUI": true
  }
}

Generated Context Output (if HOIST_CONTEXT is true):

When the get_relevant_docs tool runs, because project-overview.md has alwaysApply: true, the server would generate context like this:

<file description="Core Utilities" type="related" file="src/utils.ts">
// src/utils.ts
export function helperA() {
  console.log("Helper A");
}

export function helperB() {
  console.log("Helper B");
}
</file>

<doc description="Project Overview and Setup" type="always" file="project-overview.md">
# Project Overview

This document covers the main goals and setup instructions.

See the [Core Utilities](./src/utils.ts?md-link=true) for essential functions.

For configuration details, refer to this section: [Config Example](./config.json?md-embed=1-3)
<inline_doc description="Config Example" file="config.json" lines="2-4">
  "timeout": 5000,
  "repeats": "YOUR_API_KEY",
  "retries": 3,
</inline_doc>
</doc>

Generated Context Output (if HOIST_CONTEXT is false):

<doc description="Project Overview and Setup" type="always" file="project-overview.md">
# Project Overview

This document covers the main goals and setup instructions.

See the [Core Utilities](./src/utils.ts?md-link=true) for essential functions.

For configuration details, refer to this section: [Config Example](./config.json?md-embed=1-3)
<inline_doc description="Config Example" file="config.json" lines="2-4">
  "timeout": 5000,
  "repeats": "YOUR_API_KEY",
  "retries": 3,
</inline_doc>
</doc>

<file description="Core Utilities" type="related" file="src/utils.ts">
// src/utils.ts
export function helperA() {
  console.log("Helper A");
}

export function helperB() {
  console.log("Helper B");
}
</file>