md-chunk-lite

md-chunk-lite

Markdownを見出しごとにチャンクに分割する無料ツールです。各チャンクには、見出しの階層と元の行番号が記録されます。 PDF、Word、ウェブページのファイルを（PDFならページ番号付きで）チャンクに変換したい場合や、フォルダー全体を処理したい場合は、有料のdoc2mdをご利用ください：Gumroadのdoc2md

AI検索（RAG）、埋め込み、ドキュメントボットに適しています。AIではなく通常のコードで処理するため、同じファイルからは常に同じチャンクが生成されます。ご自身のコンピューターで実行できます。MITライセンスです。Windows、Mac、LinuxでPython 3.10以降が必要です。

インストール

pip install md-chunk-lite

または、専用の環境にインストールできるpipxを使用します：

pipx install md-chunk-lite

代わりにGitHubの最新コードを使いますか？

pip install git+https://github.com/tidybytetools/md-chunk-lite

使い方

md-chunk-lite guide.md                     # writes guide.chunks.jsonl
md-chunk-lite docs/*.md -o all.jsonl       # many files into one file
md-chunk-lite guide.md -o -                # print the chunks on screen
md-chunk-lite guide.md --max-chars 800     # smaller chunks
md-chunk-lite guide.md --outline           # just show the headings
cat guide.md | md-chunk-lite -             # read from stdin

実行例：

Saved: guide.chunks.jsonl  (7 chunks, biggest 151 chars)

.jsonlファイルの各行が1つのチャンクです：

{
  "id": "guide.md#3",
  "source": "guide.md",
  "index": 3,
  "heading_path": ["Garden Guide", "Planting", "Tomatoes"],
  "heading_level": 3,
  "anchor": "tomatoes",
  "start_line": 16,
  "end_line": 24,
  "part": 1,
  "parts": 1,
  "chars": 151,
  "text": "### Tomatoes\n\nPlant tomatoes after the last frost. Give them sun.\n\n```python\n..."
}

• heading_path：このチャンクより上にあるすべての見出しを、最上位から順に示します。
• anchor：その見出しに直接リンクできるよう、GitHubが生成する#linkです。
• start_lineとend_line：ファイル内でチャンクがある位置です（最初の行は1です）。
• partとparts：大きなセクションは複数のパートに分割されます。part 2, parts 3は、3つのうち2番目を意味します。
• chars：textの文字数です。

--outlineを指定すると、見出しが出力されます：

Garden Guide  [line 8, #garden-guide, 14 chars]
  Tools  [line 10, #tools, 47 chars]
  Planting  [line 14, #planting, 11 chars]
    Tomatoes  [line 16, #tomatoes, 151 chars]

ターミナルで実行すると、最後に有料のdoc2mdについて短い案内が1行表示されます。--quietで非表示にできます。また、出力がパイプまたはリダイレクトされる場合は表示されません。

分割方法

1. 各見出しが新しいセクションの始まりです。チャンクが複数のセクションにまたがることはないため、各チャンクには明確な見出しパスがあります。
2. 小さなセクションは1つのチャンクになります。テキストはファイルからそのままコピーされるため、行番号は一致します。
3. 大きなセクションは空行で分割されます。リスト、表、コードブロックは、収まる場合はそのまま保持されます。
4. 大きすぎる表は行ごとに分割され、各パートにヘッダー行が再度含まれます。
5. 大きすぎるコードブロックは行ごとに分割され、各パートは同じ言語の```フェンスで囲まれます。
6. 非常に長い行は、まず文末で、必要に応じてスペースの位置で分割されます。
7. 独自のテキストを持たない見出し（下位に見出しがあるだけのもの）は、独自のチャンクにはなりませんが、その下のチャンクのheading_pathには表示されます。

#見出しと、下線付き見出し（===および---）を認識します。コードブロックやYAMLフロントマター（ファイルの最上部にある---ブロック）内の見出しは無視します。

オプション：

• --max-chars N：チャンクの最大文字数（デフォルトは1500、最小は200）。英語では、約4文字が1トークンに相当します。
• --overlap-chars N：セクションを分割するとき、前のパートの末尾から最大N文字分を各パートの冒頭に含めます（デフォルトは0）。コードブロックや表の中、また異なるセクション間には追加されません。
• --prefix-path：各チャンクのテキストの冒頭に、Garden Guide > Planting > Tomatoesのような見出しパスを追加します。検索に役立つことが多いです。これは--max-charsの文字数に含まれます。
• --json：ファイルに保存する代わりに、スクリプトやAIエージェント向けのJSONオブジェクトを1つ出力します。

既知の制限

• **サイズはトークン数ではなく文字数です。**トークナイザーは読み込みません。
• **対応形式はMarkdownとプレーンテキストのみです。**PDF、Word、HTMLは読み込まれません。有料版のdoc2mdはそれらをチャンクに変換します（PDFはページ番号付き）。
• **フォルダーには対応していません。**ファイルを指定してください（シェルでdocs/*.mdを展開できます）。有料版のdoc2mdはフォルダー全体を処理します。
• **完全なMarkdownパーサーではありません。**HTMLブロック内の見出しや、複数行にまたがる下線付き見出しは、正しく処理されない場合があります。
• オーバーラップには前のパートから単語全体が使われるため、指定した文字数より少し短くなる場合があります。

Lite版と有料版

	md-chunk-lite（無料）	doc2md（有料）
読み込み形式	Markdownおよびテキストファイル	PDF、Word（.docx）、HTML
見出しパス付きでチャンク化	はい	はい
行番号とアンカー	はい	いいえ（PDFは代わりにページ番号）
各チャンクの概算トークン数	いいえ	はい
フォルダー全体とサブフォルダー	いいえ	はい
MCP サーバー	はい	いいえ

その他のおすすめ無料ツール

用途に合ったものをお選びください。LangChainをすでに使っている場合は、そのMarkdownHeaderTextSplitterでも見出しごとに分割できます。Chonkieとsemchunkは、あらゆるテキストをトークン数に基づいて分割します。md-chunk-liteは小さく、MITライセンスで、AIやトークナイザー関連の機能を含まず、行番号とアンカーを提供し、MCP サーバーを内蔵しています。

Claude DesktopまたはCursorから使う（MCP）

小型の無料MCP サーバーが内蔵されています。uvが必要です。

起動することを確認するには、手動で実行してください（アプリからの接続を静かに待ち受けます）。

uvx md-chunk-lite mcp

Claude Desktop（claude_desktop_config.json）またはCursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "md-chunk-lite": {
      "command": "uvx",
      "args": ["md-chunk-lite", "mcp"]
    }
  }
}

uvx --from md-chunk-lite md-chunk-lite-mcpを実行すると、同じサーバーが起動します。

ツール（各ツールにはファイルのpathまたはMarkdownのtextを指定します）：

ツール	機能	ファイルを変更しますか？
chunk_markdown	チャンクに分割します。一度に100件返します。続きを取得するにはstartを使います。	いいえ
outline_markdown	行番号とアンカー付きで見出しを一覧表示します。	いいえ
get_section	見出しまたはアンカーで指定したセクションを取得します。	いいえ
save_chunks_jsonl	チャンクを.jsonlファイルに保存します。	.jsonlファイルを1つ書き込みます（既存の場合は置き換えます）

いずれもインターネットは使用しません。

GitHub Actions で使用する

プッシュのたびにドキュメントをチャンクに分割することで、AI 検索やドキュメントボットは常に最新のチャンクを取得できます。また、セクションが 1 つのチャンクに収まらないほど大きい場合は、プルリクエストの該当行で警告します。

name: Docs chunks
on: [push, pull_request]
permissions:
  contents: read
jobs:
  chunks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tidybytetools/md-chunk-lite@v1
        with:
          files: docs/**/*.md
          max-chars: "1500"
          artifact-name: docs-chunks   # download the JSONL from the run page

大きなセクションを警告だけでなくチェック失敗にしたい場合は、fail-on-split: "true" を追加してください。

選択したタグと同じタグのコードを実行し、Python の標準ライブラリのみを使用します。API キーもアカウントも不要で、GitHub の外部にデータが送信されることもありません。Linux、Windows、Mac のランナーで動作します。

入力

入力	デフォルト	説明
files	**/*.md	読み込むファイルです。Glob パターンを 1 行につき 1 つ指定するか、カンマで区切って指定します。
exclude	node_modules/**, **/node_modules/**, vendor/**	対象から除外するパターンです。
max-chars	1500	チャンクの最大文字数です（200 以上）。
overlap-chars	0	前の部分から次の部分の先頭に繰り返す文字数です。
prefix-path	false	各チャンクのテキストの先頭に見出しパスを付けます。
output	md-chunks.jsonl	チャンクの保存先です。
fail-on-split	false	セクションが 1 つのチャンクに収まらない場合に失敗させます。
fail-if-no-files	true	該当するファイルがない場合に失敗させます。
artifact-name	(空)	設定すると、JSONL をこの名前のアーティファクトとしてアップロードします。
python-version	(空)	セットアップする Python です。空の場合はランナーの Python（3.10 以降）を使用します。

出力

出力	説明
files	読み込んだファイルの数です。
chunks	作成したチャンクの数です。
biggest	最大チャンクの文字数です。
split-sections	大きすぎて分割されたセクションの数です。
output	JSONL ファイルのパスです。

実行ページには、ファイルごとのチャンク数と、分割されたすべてのセクションを行番号付きで示す短いレポートも表示されます。

AI エージェント向け

• 使用する場合： Markdown またはテキストファイル（ドキュメント、メモ、README）を対象に、検索、埋め込み、または出典の引用に使う見出しパスと行番号付きのチャンクが必要な場合です。長いファイルの一部分だけを読むには、outline_markdown と get_section を使用してください。
• 使用しない場合： ファイルが PDF、Word、HTML の場合（先に変換してください）、またはトークン単位で正確なサイズが必要な場合です。
• 入力： ファイルパスまたは Markdown テキストに加え、max_chars（デフォルトは 1500）、overlap_chars（デフォルトは 0）、prefix_path（デフォルトは false）です。
• 出力： id、source、index、heading_path、heading_level、anchor、start_line、end_line、part、parts、chars、text を含むチャンクです。
• CLI の終了コードは、成功時は 0、エラー時は 1 です（メッセージは stderr に出力されます。または --json を指定すると {"ok": false, "error": ...} が出力されます）。llms.txt も参照してください。

Python

from md_chunk_lite import chunk_file, chunk_markdown, outline, get_section

chunks = chunk_file("guide.md", max_chars=1000)
for c in chunks:
    print(c["heading_path"], c["start_line"], c["end_line"])

install = get_section(open("README.md").read(), heading="Install")

チャンク分割ファイルは Python の標準ライブラリのみを使用します。pip でインストールすると、MCP サーバー用の mcp パッケージも追加されます。

テスト

pip install "mcp>=1.10,<2"
python3 -m unittest discover -s tests

mcp がインストールされていない場合、MCP のテストはスキップされます。

ライセンス

MIT です。LICENSE を参照してください。