Markdown Rules

Markdown Rules MCP サーバー

Cursor Rules や IDE 固有のルールに代わるポータブルな選択肢。

プロジェクトのドキュメントを、あらゆる MCP 対応 AI ツールで動作する標準的な Markdown ファイルを使って、インテリジェントな AI コンテキストに変換します。ベンダーロックインと散在するドキュメントから永遠に脱却しましょう。

なぜ Markdown Rules を選ぶのか？

🚀 普遍的な互換性 — 一度書けば、どこでも使えます。あなたのドキュメントは Cursor、Claude Desktop、そして将来登場するあらゆる MCP 対応 AI ツールで動作します。ベンダーロックインはありません。

🔗 スマートな依存関係の解決 — リンクされたファイルやドキュメントを自動的にたどって含めることで、手動でファイルを探したり、AI エージェントがリンクをたどることに頼ったりすることなく、複雑なプロジェクトでも AI エージェントが完全なコンテキストを受け取れるようにします。

🎯 精密なコンテキスト制御 — ファイル全体を流し込む代わりに、行範囲埋め込み（?md-embed=50-100）を使って正確なインラインコードスニペットを注入します。ノイズではなく、関連するコンテキストを取得できます。

🏗️ 複雑なコードベースに最適 — カスタムツール、社内ライブラリ、AI モデルの学習データが限られている独自フレームワークなどを持つ大規模プロジェクトに理想的です。AI があなた独自のアーキテクチャを理解するために必要なコンテキストを提供します。

前提条件 📋

• Node.js（v18 以上）
• Cursor またはその他の MCP 対応 AI コーディングツール

インストール 🛠️

Smithery 経由でのインストール

Smithery を使って、Markdown Rules MCP サーバーを IDE に自動でインストールするには：

# 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 - ドキュメントを再インデックス化します。インデックス内のドキュメントが変更された場合や、新しいドキュメントが追加された場合に便利です。

使い方 📝

AI コンテキストにどのように含めるかを定義するために、プロジェクト内に YAML フロントマター付きの .md ファイルを作成します。

ドキュメントの種類

種類	フロントマター	説明	含まれるタイミング
グローバル	alwaysApply: true	すべての AI 会話に常に含まれます	毎回自動的に
自動添付	globs: ["**/*.ts", "src/**"]	添付ファイルが glob パターンに一致する場合に含まれます	一致するファイルを添付したとき
エージェントリクエスト	description: "Brief summary"	関連性に基づいて AI が選択できるようになります	AI があなたのクエリに関連すると判断したとき
フロントマターなし	なし	プロンプトに @ 記号を使って手動で含める必要があります	AI があなたのクエリに関連すると判断したとき

フロントマターの例

グローバル (常に含まれる):

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

エージェントリクエスト (関連性に基づいて AI が選択できる):

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

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

フロントマターなし (プロンプトに @ 記号を使って手動で含める必要があります):

# 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 ツール呼び出しのばらつき

使用している特定の LLM によっては、明示的なプロンプトなしでは、モデルが期待するほど一貫して関連ドキュメントを取得するツールを呼び出さないことがあります。この動作は、markdown-rules.md ファイルの使用手順を調整するか、AI に直接ドキュメントを参照するよう依頼することで改善できることがよくあります。

個人的には、Anthropic のモデルは明示的なプロンプトなしでも非常に一貫してツールを呼び出す傾向があると感じています。

トラブルシューティング 🔧

よくある問題

1. ツール / ドキュメントが使用されない

   • MCP サーバー設定でツールが有効になっていることを確認してください
   • MCP サーバー設定で PROJECT_ROOT に絶対パスを指定していることを確認してください
   • MARKDOWN_INCLUDE が正しく、Markdown ファイルを指していることを確認してください
   • プロジェクトルートに markdown-rules.md ファイルをセットアップし、ニーズに合わせた使用手順を記載してください
   • YAML フロントマターの description フィールドを引用符で囲むようにしてください (例: description: "Project Overview")
   • globs フィールドで適切な配列構文を使用するようにしてください (例: globs: ["**/*.ts", "src/**"])
   • ドキュメントが使用されない理由をデバッグするには、list_indexed_docs ツールを使用して、利用可能なドキュメントとインデックスの内容を確認できます。「インデックスにはどのようなドキュメントがありますか?」と尋ねてみてください。

2. 新規 / 更新されたドキュメントが反映されない

   • ドキュメントまたは markdown-rules.md ファイルに変更を加えた後は、サーバーを再起動してください (まだウォッチモードはありません)

3. サーバーが見つからない

   • npm リンクが正しく設定されていることを確認してください
   • 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"
   

---

Built with ❤️ by Valstro

今後の改善

• Cursor Rules の YAML frontmatter 形式をサポートする
• MARKDOWN_INCLUDE に一致する Markdown ファイルが変更されたときにドキュメントを再インデックスするウォッチモードを追加する
• 添付できるドキュメントとコンテキストの数を制限する設定（最大深度を含む）
• 特定のファイルタイプの添付を制限する設定