Markdown Rules

Markdown Rules MCP 服务

Cursor Rules 和 IDE 专属规则的通用替代方案。

使用标准 Markdown 文件，将项目文档转化为智能 AI 上下文，可在任何兼容 MCP 的 AI 工具中使用。永久摆脱供应商锁定和散落各处的文档。

为什么选择 Markdown Rules？

🚀 通用兼容性 — 写一次，处处可用。你的文档可用于 Cursor、Claude Desktop，以及任何未来支持 MCP 的 AI 工具。没有供应商锁定。

🔗 智能依赖解析 — 自动遍历并包含链接的文件和文档，确保 AI Agent 获得复杂项目的完整上下文，无需手动查找文件，也无需依赖 AI Agent 自行跟踪链接。

🎯 精准上下文控制 — 通过行范围嵌入（?md-embed=50-100）注入精确的行内代码片段，而不是转储整个文件。获取相关上下文，而非噪音。

🏗️ 非常适合复杂代码库 — 对于带有自定义工具链、内部库或专有框架的大型项目而言是理想之选，因为 AI 模型对此类内容的训练数据有限。为它们提供理解你独特架构所需的上下文。

前提条件 📋

• Node.js（v18 或更高版本）
• Cursor 或其他支持 MCP 的 AI 编码工具

安装 🛠️

通过 Smithery 安装

通过 Smithery 为你的 IDE 自动安装 Markdown Rules MCP 服务：

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

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

其他 IDE 的安装选项请参见 Smithery。

手动安装

MacOS / Linux

{
  "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
      }
    }
  }
}

Windows

{
  "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
      }
    }
  }
}

配置使用说明（可选）

要更改默认使用说明，请在项目根目录中创建一个 markdown-rules.md 文件。该文件应包含 get_relevant_docs 工具的使用说明。

默认使用说明为：

# 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.

注意：你可以通过在 MCP 服务配置中添加 USAGE_INSTRUCTIONS_PATH 环境变量来更改默认使用说明文件的路径。

工具

• get_relevant_docs - 根据用户的查询获取相关文档。基于使用说明调用。
• list_indexed_docs - 统计并预览已索引的文档和使用说明。便于调试。
• reindex_docs - 重新索引文档。当索引中的文档已发生变化或添加了新文档时很有用。

如何使用 📝

在项目中使用 YAML frontmatter 创建 .md 文件，以定义它们应如何包含在 AI 上下文中。

文档类型

类型	Frontmatter	描述	何时包含
全局	alwaysApply: true	始终包含在每次 AI 对话中	自动，每次
自动附加	globs: ["**/*.ts", "src/**"]	当附加的文件匹配 glob 模式时包含	当你附加匹配的文件时
Agent 请求	description: "Brief summary"	可供 AI 根据相关性选择	当 AI 判断其与你的查询相关时
无 Frontmatter	无	必须使用 @ 符号手动包含在提示词中	当 AI 判断其与你的查询相关时

Frontmatter 示例

全局（始终包含）：

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

This doc will always be included.

自动附加（当附加 TypeScript 文件时包含）：

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

This doc will be included when TypeScript files are attached.

Agent 请求（可由 AI 根据相关性选择）：

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

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

无 frontmatter（必须使用 @ 符号手动包含在提示词中）：

# Testing Guidelines

This doc needs manual inclusion with @ symbol

链接文件

链接其他文件： 添加 ?md-link=true 以将链接的文件包含在上下文中

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

嵌入特定行： 添加 ?md-embed=START-END 以仅内联包含特定行

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

配置

• PROJECT_ROOT - 默认值：process.cwd() - 项目根目录的绝对路径。
• MARKDOWN_INCLUDE - 默认值：**/*.md - 用于查找 markdown 文档文件的模式
• HOIST_CONTEXT - 默认值：true - 是否在引用链接文件的文档之前显示这些链接文件
• MARKDOWN_EXCLUDE - 默认值：**/node_modules/**,**/build/**,**/dist/**,**/.git/**,**/coverage/**,**/.next/**,**/.nuxt/**,**/out/**,**/.cache/**,**/tmp/**,**/temp/** - 查找 markdown 文件时要忽略的模式

示例 📝

假设你的项目中有以下文件：

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
  }
}

生成的上下文输出（如果 HOIST_CONTEXT 为 true）：

当 get_relevant_docs 工具运行时，由于 project-overview.md 具有 alwaysApply: true，服务会生成如下上下文：

<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>

生成的上下文输出（如果 HOIST_CONTEXT 为 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>

注意事项与潜在缺点

上下文可能过大

Markdown Rules 会勤勉地解析所有 markdown 链接（?md-link=true）和嵌入（例如 ?md-embed=1-10），以包含引用的内容。这种全面性可能会导致占用 AI 上下文窗口的很大一部分，尤其是在文档链接层次很深的情况下。

不过，我认为对于这个工具所面向的大型定制代码库而言，为了提供完整的上下文，这是一种必要的权衡。

MCP 工具调用差异

有时，取决于你使用的具体大模型，在没有明确提示的情况下，模型可能不会像人们期望的那样始终如一地调用工具来获取相关文档。通常可以通过调整 markdown-rules.md 文件中的使用说明，或直接要求 AI 查阅文档来改善这种行为。

我个人发现 Anthropic 模型往往无需明确提示就能非常稳定地调用该工具。

故障排除 🔧

常见问题

1. 工具／文档未被使用

   • 确保在 MCP 服务配置中启用了该工具
   • 确保在 MCP 服务配置中为 PROJECT_ROOT 提供了绝对路径
   • 确保你的 MARKDOWN_INCLUDE 正确并指向 markdown 文件
   • 在项目根目录中设置 markdown-rules.md 文件，并根据你的需求编写使用说明
   • 确保在 YAML frontmatter 中用引号包裹 description 字段（例如 description: "Project Overview"）
   • 确保在 globs 字段中使用正确的数组语法（例如 globs: ["**/*.ts", "src/**"]）
   • 如需调试文档未被使用的原因，你可以使用 list_indexed_docs 工具查看有哪些文档可用以及索引中包含什么内容。只需询问"索引中有哪些可用文档？"

2. 新增／更新的文档未被反映

   • 确保在更改文档或 markdown-rules.md 文件后重启服务（目前还没有监听模式）

3. 找不到服务

   • 验证 npm link 是否正确设置
   • 检查 Cursor 配置语法
   • 确保 Node.js 已正确安装（v18 或更高版本）

4. 配置问题

   • 确保你的 MARKDOWN_INCLUDE 正确

5. 连接问题

   • 完全重启 Cursor
   • 检查 Cursor 日志：

   # macOS
   tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
   
   # Windows
   type "%APPDATA%\Claude\logs\mcp*.log"
   

---

由 Valstro 用 ❤️ 构建

未来改进

• 支持 Cursor Rules YAML frontmatter 格式
• 添加 watch 模式，当匹配 MARKDOWN_INCLUDE 的 markdown 文件发生变化时重新索引文档
• 通过配置限制可附加的文档和上下文数量，包括最大深度。
• 通过配置限制某些文件类型不被附加。