md-vision

md-vision MCP サーバー

Markdown ドキュメントを対象とするエージェント型 RAG 用の、読み取り専用ツールを 2 つ備えた stdio MCP サーバーです。

• read_md_with_images — 参照されている画像をインターリーブされた画像ブロックとして含めた Markdown を返します。画像を読み取るための追加のツール呼び出しが不要になります。特定のセクションまたは行範囲に絞り込むこともできます。
• index_md — ファイル、URL、または Markdown ファイルのフォルダーについて、簡潔な見出しインデックスを返します。対象を絞って読み取るファイルを動的にインデックス化するために使用します。

一般的な流れ：index_md を呼び出して見出しと構造を確認し、必要なセクションに対して read_md_with_images を呼び出します。

インストール：MCP クライアントの設定

公開パッケージ：npm の md-vision

エージェント設定（.agents/mcp.json など）で、MCP ホストの接続先としてサーバーを指定します。例：

{
  "mcpServers": {
    "md-vision": {
      "command": "npx",
      "args": [
        "md-vision",
        "--allow-path",
        "/absolute/path/to/docs",
        "--allow-domain",
        "none"
      ]
    }
  }
}

リモート Markdown の場合（すべての HTTP(S) ホストを許可するか、特定のドメインを指定します）：

{
  "mcpServers": {
    "md-vision": {
      "command": "npx",
      "args": [
        "md-vision",
        "--allow-path",
        "/absolute/path/to/docs",
        "--allow-domain",
        "all"
      ]
    }
  }
}

{
  "mcpServers": {
    "md-vision": {
      "command": "npx",
      "args": [
        "md-vision",
        "--allow-path",
        "/absolute/path/to/docs",
        "--allow-domain",
        "raw.githubusercontent.com"
      ]
    }
  }
}

--allow-path または --allow-domain が省略されている場合、サーバーは起動時に終了します。

設定を変更した後は、MCP ホストを再起動してください。

許可するパスとドメインの制限

フラグ	必須	動作
--allow-path <dir>	はい（少なくとも 1 つ）	ローカルファイルは、許可されたディレクトリのいずれかの下に解決される必要があります（複数指定可能）。
--allow-domain <host>	はい（少なくとも 1 つ）	HTTP(S) アクセスを制御します。すべてのホストを許可するには all、URL を無効にするには none（ローカルファイルのみ）、特定のホストを指定するにはホスト名を使用します（複数指定可能。サフィックス一致に対応しており、例：example.com は docs.example.com を許可します）。

同等の形式：--allow-path=/path、--allow-domain=host.example、--allow-domain=all、--allow-domain=none。

シェルが現在のディレクトリ内のファイル名に展開するため、単独の * をシェル引数として渡さないでください。代わりに all または --allow-domain=all を使用してください。

要件

• Node.js 20+

ツール

read_md_with_images

Markdown ファイルを読み取り、参照されている画像を MCP の画像コンテンツとしてインライン表示します。

パラメーター	型	説明
uri	string	ローカルパスまたは http(s):// URL
section	string、任意	読み取る見出しを完全一致で指定します。例：## Introduction（一致した場合に使用し、それ以外の場合は line_range にフォールバックします）
line_range	[start, end]、任意	文書内の 1 始まりの行範囲（終端行を含みます）。section が省略されているか見つからない場合に使用します。
max_images	integer、任意	インライン表示する画像の最大数（デフォルトは 10、最大は 50）

戻り値： MCP コンテンツ配列。文書の順序に従って text ブロックと image ブロック（PNG、base64）が交互に並びます。先頭のテキストにはフロントマターが保持されます。インライン表示する各画像の前には、解決された画像 URL を含む短い text ブロックが置かれます（data: URI およびその他の長い参照の場合は省略）。max_images を超える画像は、テキスト内に Markdown の画像構文で残ります。

URI の形式： ローカルファイルシステムパスおよび http(s):// URL。ローカルパスは、設定済みの --allow-path ディレクトリの配下にある必要があります。相対画像パスは、Markdown ファイルの場所または文書 URL を基準に解決されます。画像には Markdown の ![](...) 構文または HTML の <img src="..."> タグを使用できます。

index_md

対象を絞って読み取る前に、ナビゲーション用の見出しをインデックス化します。

パラメーター	型	説明
uri	string	Markdown ファイル、http(s):// URL、またはローカルフォルダー

戻り値： Markdown 文字列。各ファイルについて：

1. YAML フロントマターがある場合は、その内容。
2. heading、line_start、n_images、char_count の列を含む、フェンス付き tsv コードブロック。

各ファイルは次の形式で囲まれます。

<file path="..." lines=X chars=Y>
...
</file>

フォルダーを指定した uri は、*.md／*.markdown を安定した並べ替え順で再帰的に走査します。フェンス付きコードブロック内の見出しはインデックス化されません。

この MCP サーバーでエージェントをデプロイする際の注意点

stdio MCP サーバーは、呼び出し元のエージェントランタイムのサブプロセスとして実行されます。一般的に使用されるデプロイパターンは 2 つあります。

• サンドボックス内のエージェント（ランタイムがエージェントと同じファイルシステムを共有）：サーバーはドキュメントをその場で読み取れます。公開するドキュメントのツリーに --allow-path の範囲を限定してください。
• ツールとしてのサンドボックス（ランタイムのファイルシステムがツールのサンドボックスと異なる）：MCP プロセスは通常、ランタイム環境で実行されるため、サーバーが読み取れる場所に Markdown をコピーまたは同期する必要があります。

ベンチマーク（作業中）

benchmark/ で、ファイルシステムのみを使うエージェント型 RAG と、同じエージェントに md-vision MCP ツールを追加した場合を比較する MMLongBench-Doc の A/B テストハーネスを確認してください。

スタンドアロンでのインデックス作成

md-vision は、MCP ホストを介さずに Markdown のインデックスを作成したい場合にも、ライブラリとして使用できます。たとえば、エージェント型 RAG のオフライン前処理パイプラインで使用できます。

パッケージをインストールします。

npm install md-vision

Markdown テキストのインデックス作成

Markdown コンテンツがすでにメモリ上にある場合は、indexMarkdownText を使用します。

import { indexMarkdownText } from "md-vision";

const markdown = `# Guide

Intro text.

## Setup

![diagram](./setup.png)
`;

const index = indexMarkdownText(markdown);

console.log(index.rows);

実行結果の例：

[
  {
    heading: "# Guide",
    lineStart: 1,
    imageCount: 1,
    charCount: 42
  },
  {
    heading: "## Setup",
    lineStart: 5,
    imageCount: 1,
    charCount: 24
  }
]

ファイルのインデックス作成

indexMarkdownFile を使用して、ローカルの Markdown ファイルを読み込み、インデックスを作成します。

import { indexMarkdownFile } from "md-vision";

const index = await indexMarkdownFile("./docs/guide.md");

await saveToVectorStoreMetadata({
  path: index.path,
  frontmatter: index.frontmatter,
  headings: index.rows,
});

フォルダーのインデックス作成

indexMarkdownFolder を使用して、*.md ファイルと *.markdown ファイルを再帰的に、順序を一定に保ってインデックス化します。

import { indexMarkdownFolder } from "md-vision";

const files = await indexMarkdownFolder("./docs");

for (const file of files) {
  console.log(file.path, file.rows);
}

出力形式

インデックス化された各ファイルは、構造化データを返します。

type MarkdownFileIndex = {
  path?: string;
  frontmatter: string;
  lineCount: number;
  charCount: number;
  rows: HeadingIndexRow[];
};

type HeadingIndexRow = {
  heading: string;
  lineStart: number;
  imageCount: number;
  charCount: number;
};

フェンス付きコードブロック内の見出しは、正規表現ではなく Markdown AST を使ってインデックスを作成するため、無視されます。