Show HN: Markdown Rules MCP Server – The Portable Alternative to Cursor Rules

22 hours ago 2

The portable alternative to Cursor Rules and IDE-specific rules.

Transform your project documentation into intelligent AI context using standard Markdown files that work across any MCP-compatible AI tool. Escape vendor lock-in and scattered documentation forever.

Why Choose Markdown Rules?

🚀 Universal Compatibility — Write once, use everywhere. Your documentation works with Cursor, Claude Desktop, and any future MCP-enabled AI tool. No vendor lock-in.

🔗 Smart Dependency Resolution — Automatically traverse and include linked files & docs, ensuring AI agents receive complete context for complex projects without manual file hunting or relying on the AI agent to follow links.

🎯 Precision Context Control — Inject exact inline code snippets with line-range embeds (?md-embed=50-100) instead of dumping entire files. Get relevant context, not noise.

🏗️ Perfect for Complex Codebases — Ideal for large projects with custom tooling, internal libraries, or proprietary frameworks that AI models have limited training data for. Provide the context they need to understand your unique architecture.

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

To install the Markdown Rules MCP server for your IDE automatically via Smithery:

# Cursor npx -y @smithery/cli install markdown-rules-mcp --client cursor

# Windsurf npx -y @smithery/cli install markdown-rules-mcp --client windsurf

See Smithery for installation options for other IDEs.

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

{ "mcpServers": { "markdown-rules-mcp": { "command": "cmd.exe", "args": [ "/c", "npx", "-y", "@valstro/markdown-rules-mcp@latest" ], "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.

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.

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

Type Frontmatter Description When Included

Global	alwaysApply: true	Always included in every AI conversation	Automatically, every time
Auto-Attached	globs: ["*/.ts", "src/**"]	Included when attached files match the glob patterns	When you attach matching files
Agent-Requested	description: "Brief summary"	Available for AI to select based on relevance	When AI determines it's relevant to your query
No Frontmatter	None	Must be included in the prompt manually with @ symbol	When AI determines it's relevant to your query

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

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)

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

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>

Caveats & Potential Downsides

Potentially Large Context

Markdown Rules will diligently parse through all markdown links (?md-link=true) and embeds (e.g., ?md-embed=1-10) to include referenced content. This comprehensiveness can lead to using a significant portion of the AI's context window, especially with deeply linked documentation.

However, I find this to be a necessary trade-off for providing complete context in the large, bespoke codebases this tool is designed for.

MCP Tool Invocation Variance

Occasionally, depending on the specific LLM you're using, the model might not call the tool to fetch relevant docs as consistently as one might hope without explicit prompting. This behavior can often be improved by tweaking the usage instructions in your markdown-rules.md file or by directly asking the AI to consult the docs.

I've personally found Anthropic models tend to call the tool very consistently without needing explicit prompts.

Tool / Docs Not Being Used
- Ensure the tool is enabled in the MCP server configuration
- Make sure you're providing an absolute path to the PROJECT_ROOT in the MCP server configuration
- Make sure your MARKDOWN_INCLUDE is correct & points to markdown files
- Setup markdown-rules.md file in your project root with usage instructions for your needs
- Make sure to wrap your description field in YAML frontmatter in quotes (e.g. description: "Project Overview")
- Make sure to use proper array syntax in the globs field (e.g. globs: ["**/*.ts", "src/**"])
- To debug why your doc isn't being used, you can use the list_indexed_docs tool to see what docs are available and what's in the index. Just ask "what docs are available in the index?"
New/Updated Docs Not Being Reflected
- Make sure to restart the server after making changes to docs or the markdown-rules.md file (there's no watch mode yet)
Server Not Found
- Verify the npm link is correctly set up
- Check Cursor configuration syntax
- Ensure Node.js is properly installed (v18 or higher)
Configuration Issues
- Make sure your MARKDOWN_INCLUDE is correct
Connection Issues
- Restart Cursor completely
- Check Cursor logs:
# macOS tail -n 20 -f ~/Library/Logs/Claude/mcp*.log # Windows type "%APPDATA%\Claude\logs\mcp*.log"

Built with ❤️ by Valstro

Support Cursor Rules YAML frontmatter format
Add watch mode to re-index docs when markdown files matching the MARKDOWN_INCLUDE have changed
Config to limit the number of docs & context that can be attached including a max depth.
Config to restrict certain file types from being attached.

Read Entire Article