md-chunk-lite 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- md_chunk_lite-1.0.0/CHANGELOG.md +12 -0
- md_chunk_lite-1.0.0/LICENSE +9 -0
- md_chunk_lite-1.0.0/MANIFEST.in +4 -0
- md_chunk_lite-1.0.0/PKG-INFO +236 -0
- md_chunk_lite-1.0.0/README.md +206 -0
- md_chunk_lite-1.0.0/llms.txt +21 -0
- md_chunk_lite-1.0.0/md_chunk_lite.egg-info/PKG-INFO +236 -0
- md_chunk_lite-1.0.0/md_chunk_lite.egg-info/SOURCES.txt +18 -0
- md_chunk_lite-1.0.0/md_chunk_lite.egg-info/dependency_links.txt +1 -0
- md_chunk_lite-1.0.0/md_chunk_lite.egg-info/entry_points.txt +3 -0
- md_chunk_lite-1.0.0/md_chunk_lite.egg-info/requires.txt +1 -0
- md_chunk_lite-1.0.0/md_chunk_lite.egg-info/top_level.txt +2 -0
- md_chunk_lite-1.0.0/md_chunk_lite.py +535 -0
- md_chunk_lite-1.0.0/md_chunk_lite_mcp.py +164 -0
- md_chunk_lite-1.0.0/pyproject.toml +45 -0
- md_chunk_lite-1.0.0/server.json +31 -0
- md_chunk_lite-1.0.0/setup.cfg +4 -0
- md_chunk_lite-1.0.0/tests/fixtures/guide.md +42 -0
- md_chunk_lite-1.0.0/tests/test_chunk.py +281 -0
- md_chunk_lite-1.0.0/tests/test_mcp.py +102 -0
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
What changed in md-chunk-lite, newest first.
|
|
4
|
+
|
|
5
|
+
## 1.0.0 - 2026-11-04
|
|
6
|
+
|
|
7
|
+
- First release.
|
|
8
|
+
- Splits Markdown into chunks by heading. Each chunk keeps its heading path, anchor and start and end line numbers.
|
|
9
|
+
- Big sections are split at blank lines. Tables repeat their header row and code blocks get their fence again when they must be split.
|
|
10
|
+
- Options: `--max-chars`, `--overlap-chars`, `--prefix-path`, `--outline` and `--json`.
|
|
11
|
+
- Free MCP server with four tools: `chunk_markdown`, `outline_markdown`, `get_section` and `save_chunks_jsonl`. Start it with `uvx md-chunk-lite mcp`.
|
|
12
|
+
- Needs Python 3.10 or newer.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 tidybyte
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: md-chunk-lite
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Split Markdown into chunks by heading. Each chunk keeps its heading path and line numbers. CLI and MCP server. Runs locally.
|
|
5
|
+
Author: Tidy Byte Tools
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/tidybytetools/md-chunk-lite
|
|
8
|
+
Project-URL: Source, https://github.com/tidybytetools/md-chunk-lite
|
|
9
|
+
Project-URL: Issues, https://github.com/tidybytetools/md-chunk-lite/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/tidybytetools/md-chunk-lite/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: markdown,chunking,text-splitter,rag,llm,embeddings,headings,jsonl,cli,mcp,mcp-server
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Text Processing :: Markup :: Markdown
|
|
23
|
+
Classifier: Topic :: Text Processing :: Indexing
|
|
24
|
+
Classifier: Topic :: Utilities
|
|
25
|
+
Requires-Python: >=3.10
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
License-File: LICENSE
|
|
28
|
+
Requires-Dist: mcp<2,>=1.10
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
|
|
31
|
+
<p>
|
|
32
|
+
<a href="https://github.com/tidybytetools">
|
|
33
|
+
<picture>
|
|
34
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tidybytetools/md-chunk-lite/main/assets/tidybytetools-lockup-dark.png">
|
|
35
|
+
<img alt="Tidy Byte Tools" src="https://raw.githubusercontent.com/tidybytetools/md-chunk-lite/main/assets/tidybytetools-lockup-light.png" height="44">
|
|
36
|
+
</picture>
|
|
37
|
+
</a>
|
|
38
|
+
</p>
|
|
39
|
+
|
|
40
|
+
# md-chunk-lite
|
|
41
|
+
|
|
42
|
+
[](https://github.com/tidybytetools/md-chunk-lite/blob/main/LICENSE)
|
|
43
|
+
[](https://www.python.org/)
|
|
44
|
+
[](#use-it-from-claude-desktop-or-cursor-mcp)
|
|
45
|
+
[](https://github.com/tidybytetools/md-chunk-lite/actions/workflows/tests.yml)
|
|
46
|
+
|
|
47
|
+
Free tool that splits Markdown into chunks by heading. Every chunk knows its heading path and the line numbers it came from.
|
|
48
|
+
Need PDF, Word or web page files turned into chunks (with page numbers for PDFs), or whole folders? The paid doc2md does that: **[doc2md on Gumroad](https://tidybyte.gumroad.com/l/frlkv)**
|
|
49
|
+
|
|
50
|
+
Good for AI search (RAG), embeddings, and docs bots. Plain code, not AI, so the same file always gives the same chunks. Runs on your own computer. MIT license. Python 3.10 or newer, on Windows, Mac and Linux.
|
|
51
|
+
|
|
52
|
+
<!-- mcp-name: io.github.tidybytetools/md-chunk-lite -->
|
|
53
|
+
|
|
54
|
+
## Install
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
pip install md-chunk-lite
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Or use pipx, which keeps it in its own space:
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
pipx install md-chunk-lite
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Want the newest code from GitHub instead?
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
pip install git+https://github.com/tidybytetools/md-chunk-lite
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Use it
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
md-chunk-lite guide.md # writes guide.chunks.jsonl
|
|
76
|
+
md-chunk-lite docs/*.md -o all.jsonl # many files into one file
|
|
77
|
+
md-chunk-lite guide.md -o - # print the chunks on screen
|
|
78
|
+
md-chunk-lite guide.md --max-chars 800 # smaller chunks
|
|
79
|
+
md-chunk-lite guide.md --outline # just show the headings
|
|
80
|
+
cat guide.md | md-chunk-lite - # read from stdin
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Example run:
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
Saved: guide.chunks.jsonl (7 chunks, biggest 151 chars)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Each line of the `.jsonl` file is one chunk:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{
|
|
93
|
+
"id": "guide.md#3",
|
|
94
|
+
"source": "guide.md",
|
|
95
|
+
"index": 3,
|
|
96
|
+
"heading_path": ["Garden Guide", "Planting", "Tomatoes"],
|
|
97
|
+
"heading_level": 3,
|
|
98
|
+
"anchor": "tomatoes",
|
|
99
|
+
"start_line": 16,
|
|
100
|
+
"end_line": 24,
|
|
101
|
+
"part": 1,
|
|
102
|
+
"parts": 1,
|
|
103
|
+
"chars": 151,
|
|
104
|
+
"text": "### Tomatoes\n\nPlant tomatoes after the last frost. Give them sun.\n\n```python\n..."
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
- `heading_path`: all the headings above this chunk, from the top.
|
|
109
|
+
- `anchor`: the `#link` GitHub makes for that heading, so you can link straight to it.
|
|
110
|
+
- `start_line` and `end_line`: where the chunk is in the file (the first line is 1).
|
|
111
|
+
- `part` and `parts`: a big section is split into parts. `part 2, parts 3` means the 2nd of 3.
|
|
112
|
+
- `chars`: how long `text` is.
|
|
113
|
+
|
|
114
|
+
`--outline` prints the headings:
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
Garden Guide [line 8, #garden-guide, 14 chars]
|
|
118
|
+
Tools [line 10, #tools, 47 chars]
|
|
119
|
+
Planting [line 14, #planting, 11 chars]
|
|
120
|
+
Tomatoes [line 16, #tomatoes, 151 chars]
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
When you run it in a terminal it ends with one short line about the paid doc2md. `--quiet` turns it off, and it never shows when output is piped or redirected.
|
|
124
|
+
|
|
125
|
+
## How it splits
|
|
126
|
+
|
|
127
|
+
1. Each heading starts a new section. A chunk never mixes two sections, so every chunk has one clear heading path.
|
|
128
|
+
2. A small section becomes one chunk. Its text is copied straight from your file, so the line numbers match.
|
|
129
|
+
3. A big section is split at blank lines. Lists, tables and code blocks stay whole when they fit.
|
|
130
|
+
4. A table that is too big is split by rows, and each part gets the header row again.
|
|
131
|
+
5. A code block that is too big is split by lines, and each part gets its own ``` fence again, with the same language.
|
|
132
|
+
6. A very long line is cut at the end of a sentence, then at a space if it has to be.
|
|
133
|
+
7. A heading with no text of its own (just more headings under it) does not get its own chunk, but it still shows in the `heading_path` of the chunks under it.
|
|
134
|
+
|
|
135
|
+
It knows `#` headings and underlined headings (`===` and `---`). It skips headings inside code blocks and YAML front matter (the `---` block at the very top).
|
|
136
|
+
|
|
137
|
+
Options:
|
|
138
|
+
|
|
139
|
+
- `--max-chars N`: biggest chunk, in characters (default 1500, smallest 200). About 4 characters make 1 token in English.
|
|
140
|
+
- `--overlap-chars N`: when a section is split, start each part with up to N characters from the end of the part before it (default 0). It is never added inside a code block or table, and never between two different sections.
|
|
141
|
+
- `--prefix-path`: start each chunk's text with its heading path, like `Garden Guide > Planting > Tomatoes`. This often helps search. It counts toward `--max-chars`.
|
|
142
|
+
- `--json`: print one JSON object for scripts and AI agents instead of saving a file.
|
|
143
|
+
|
|
144
|
+
## Known limits
|
|
145
|
+
|
|
146
|
+
- **Sizes are characters, not tokens.** It does not load a tokenizer.
|
|
147
|
+
- **Markdown and plain text only.** PDF, Word and HTML are not read. The paid doc2md turns those into chunks (with page numbers for PDFs).
|
|
148
|
+
- **No folders.** Give it files (your shell can expand `docs/*.md`). The paid doc2md walks whole folders.
|
|
149
|
+
- **Not a full Markdown parser.** A heading inside an HTML block, or an underlined heading that spans more than one line, may be handled wrong.
|
|
150
|
+
- **Overlap uses whole words** from the part before, so it can be a little shorter than you asked for.
|
|
151
|
+
|
|
152
|
+
## Lite vs paid
|
|
153
|
+
|
|
154
|
+
| | md-chunk-lite (free) | [doc2md](https://tidybyte.gumroad.com/l/frlkv) (paid) |
|
|
155
|
+
|---|---|---|
|
|
156
|
+
| Reads | Markdown and text files | PDF, Word (.docx) and HTML |
|
|
157
|
+
| Chunks with the heading path | yes | yes |
|
|
158
|
+
| Line numbers and anchors | yes | no (page numbers for PDFs instead) |
|
|
159
|
+
| Rough token count on each chunk | no | yes |
|
|
160
|
+
| Whole folders, sub-folders too | no | yes |
|
|
161
|
+
| MCP server | yes | no |
|
|
162
|
+
|
|
163
|
+
## Other good free tools
|
|
164
|
+
|
|
165
|
+
Pick what fits you. If you already use LangChain, its `MarkdownHeaderTextSplitter` also splits by heading. [Chonkie](https://github.com/feyninc/chonkie) and [semchunk](https://github.com/isaacus-dev/semchunk) split any text by token count. md-chunk-lite is small, MIT, has no AI or tokenizer parts, gives you line numbers and anchors, and has an MCP server built in.
|
|
166
|
+
|
|
167
|
+
## Use it from Claude Desktop or Cursor (MCP)
|
|
168
|
+
|
|
169
|
+
There is a small free MCP server built in. It needs [uv](https://docs.astral.sh/uv/).
|
|
170
|
+
|
|
171
|
+
Run it by hand to check it starts (it waits quietly for an app to talk to it):
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
uvx md-chunk-lite mcp
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Claude Desktop (`claude_desktop_config.json`) or Cursor (`~/.cursor/mcp.json`):
|
|
178
|
+
|
|
179
|
+
```json
|
|
180
|
+
{
|
|
181
|
+
"mcpServers": {
|
|
182
|
+
"md-chunk-lite": {
|
|
183
|
+
"command": "uvx",
|
|
184
|
+
"args": ["md-chunk-lite", "mcp"]
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
`uvx --from md-chunk-lite md-chunk-lite-mcp` starts the same server.
|
|
191
|
+
|
|
192
|
+
Tools (each one takes a file `path` or Markdown `text`):
|
|
193
|
+
|
|
194
|
+
| Tool | What it does | Changes files? |
|
|
195
|
+
|---|---|---|
|
|
196
|
+
| `chunk_markdown` | Splits into chunks. Returns 100 at a time; use `start` for more. | No |
|
|
197
|
+
| `outline_markdown` | Lists the headings with line numbers and anchors. | No |
|
|
198
|
+
| `get_section` | Gets one section by heading or anchor. | No |
|
|
199
|
+
| `save_chunks_jsonl` | Saves the chunks to a `.jsonl` file. | Writes one `.jsonl` file (replaces it if it is there) |
|
|
200
|
+
|
|
201
|
+
None of them use the internet.
|
|
202
|
+
|
|
203
|
+
## For AI agents
|
|
204
|
+
|
|
205
|
+
- **Use when:** you have a Markdown or text file (docs, notes, a README) and need chunks with heading paths and line numbers for search, embeddings or citing sources. Use `outline_markdown` and `get_section` to read just one part of a long file.
|
|
206
|
+
- **Don't use when:** the file is PDF, Word or HTML (convert it first), or you need token-exact sizes.
|
|
207
|
+
- **Input:** a file path or Markdown text, plus `max_chars` (default 1500), `overlap_chars` (default 0) and `prefix_path` (default false).
|
|
208
|
+
- **Output:** chunks with `id`, `source`, `index`, `heading_path`, `heading_level`, `anchor`, `start_line`, `end_line`, `part`, `parts`, `chars`, `text`.
|
|
209
|
+
- CLI exit code is 0 on success and 1 on error (message on stderr, or `{"ok": false, "error": ...}` with `--json`). See also [`llms.txt`](https://github.com/tidybytetools/md-chunk-lite/blob/main/llms.txt).
|
|
210
|
+
|
|
211
|
+
## Python
|
|
212
|
+
|
|
213
|
+
```python
|
|
214
|
+
from md_chunk_lite import chunk_file, chunk_markdown, outline, get_section
|
|
215
|
+
|
|
216
|
+
chunks = chunk_file("guide.md", max_chars=1000)
|
|
217
|
+
for c in chunks:
|
|
218
|
+
print(c["heading_path"], c["start_line"], c["end_line"])
|
|
219
|
+
|
|
220
|
+
install = get_section(open("README.md").read(), heading="Install")
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
The chunker file uses only Python's standard library. Installing with pip also adds the `mcp` package for the MCP server.
|
|
224
|
+
|
|
225
|
+
## Tests
|
|
226
|
+
|
|
227
|
+
```
|
|
228
|
+
pip install "mcp>=1.10,<2"
|
|
229
|
+
python3 -m unittest discover -s tests
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
The MCP tests are skipped if `mcp` is not installed.
|
|
233
|
+
|
|
234
|
+
## License
|
|
235
|
+
|
|
236
|
+
MIT. See `LICENSE`.
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
<p>
|
|
2
|
+
<a href="https://github.com/tidybytetools">
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tidybytetools/md-chunk-lite/main/assets/tidybytetools-lockup-dark.png">
|
|
5
|
+
<img alt="Tidy Byte Tools" src="https://raw.githubusercontent.com/tidybytetools/md-chunk-lite/main/assets/tidybytetools-lockup-light.png" height="44">
|
|
6
|
+
</picture>
|
|
7
|
+
</a>
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
# md-chunk-lite
|
|
11
|
+
|
|
12
|
+
[](https://github.com/tidybytetools/md-chunk-lite/blob/main/LICENSE)
|
|
13
|
+
[](https://www.python.org/)
|
|
14
|
+
[](#use-it-from-claude-desktop-or-cursor-mcp)
|
|
15
|
+
[](https://github.com/tidybytetools/md-chunk-lite/actions/workflows/tests.yml)
|
|
16
|
+
|
|
17
|
+
Free tool that splits Markdown into chunks by heading. Every chunk knows its heading path and the line numbers it came from.
|
|
18
|
+
Need PDF, Word or web page files turned into chunks (with page numbers for PDFs), or whole folders? The paid doc2md does that: **[doc2md on Gumroad](https://tidybyte.gumroad.com/l/frlkv)**
|
|
19
|
+
|
|
20
|
+
Good for AI search (RAG), embeddings, and docs bots. Plain code, not AI, so the same file always gives the same chunks. Runs on your own computer. MIT license. Python 3.10 or newer, on Windows, Mac and Linux.
|
|
21
|
+
|
|
22
|
+
<!-- mcp-name: io.github.tidybytetools/md-chunk-lite -->
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
pip install md-chunk-lite
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Or use pipx, which keeps it in its own space:
|
|
31
|
+
|
|
32
|
+
```
|
|
33
|
+
pipx install md-chunk-lite
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Want the newest code from GitHub instead?
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
pip install git+https://github.com/tidybytetools/md-chunk-lite
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Use it
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
md-chunk-lite guide.md # writes guide.chunks.jsonl
|
|
46
|
+
md-chunk-lite docs/*.md -o all.jsonl # many files into one file
|
|
47
|
+
md-chunk-lite guide.md -o - # print the chunks on screen
|
|
48
|
+
md-chunk-lite guide.md --max-chars 800 # smaller chunks
|
|
49
|
+
md-chunk-lite guide.md --outline # just show the headings
|
|
50
|
+
cat guide.md | md-chunk-lite - # read from stdin
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Example run:
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
Saved: guide.chunks.jsonl (7 chunks, biggest 151 chars)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Each line of the `.jsonl` file is one chunk:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"id": "guide.md#3",
|
|
64
|
+
"source": "guide.md",
|
|
65
|
+
"index": 3,
|
|
66
|
+
"heading_path": ["Garden Guide", "Planting", "Tomatoes"],
|
|
67
|
+
"heading_level": 3,
|
|
68
|
+
"anchor": "tomatoes",
|
|
69
|
+
"start_line": 16,
|
|
70
|
+
"end_line": 24,
|
|
71
|
+
"part": 1,
|
|
72
|
+
"parts": 1,
|
|
73
|
+
"chars": 151,
|
|
74
|
+
"text": "### Tomatoes\n\nPlant tomatoes after the last frost. Give them sun.\n\n```python\n..."
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- `heading_path`: all the headings above this chunk, from the top.
|
|
79
|
+
- `anchor`: the `#link` GitHub makes for that heading, so you can link straight to it.
|
|
80
|
+
- `start_line` and `end_line`: where the chunk is in the file (the first line is 1).
|
|
81
|
+
- `part` and `parts`: a big section is split into parts. `part 2, parts 3` means the 2nd of 3.
|
|
82
|
+
- `chars`: how long `text` is.
|
|
83
|
+
|
|
84
|
+
`--outline` prints the headings:
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
Garden Guide [line 8, #garden-guide, 14 chars]
|
|
88
|
+
Tools [line 10, #tools, 47 chars]
|
|
89
|
+
Planting [line 14, #planting, 11 chars]
|
|
90
|
+
Tomatoes [line 16, #tomatoes, 151 chars]
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
When you run it in a terminal it ends with one short line about the paid doc2md. `--quiet` turns it off, and it never shows when output is piped or redirected.
|
|
94
|
+
|
|
95
|
+
## How it splits
|
|
96
|
+
|
|
97
|
+
1. Each heading starts a new section. A chunk never mixes two sections, so every chunk has one clear heading path.
|
|
98
|
+
2. A small section becomes one chunk. Its text is copied straight from your file, so the line numbers match.
|
|
99
|
+
3. A big section is split at blank lines. Lists, tables and code blocks stay whole when they fit.
|
|
100
|
+
4. A table that is too big is split by rows, and each part gets the header row again.
|
|
101
|
+
5. A code block that is too big is split by lines, and each part gets its own ``` fence again, with the same language.
|
|
102
|
+
6. A very long line is cut at the end of a sentence, then at a space if it has to be.
|
|
103
|
+
7. A heading with no text of its own (just more headings under it) does not get its own chunk, but it still shows in the `heading_path` of the chunks under it.
|
|
104
|
+
|
|
105
|
+
It knows `#` headings and underlined headings (`===` and `---`). It skips headings inside code blocks and YAML front matter (the `---` block at the very top).
|
|
106
|
+
|
|
107
|
+
Options:
|
|
108
|
+
|
|
109
|
+
- `--max-chars N`: biggest chunk, in characters (default 1500, smallest 200). About 4 characters make 1 token in English.
|
|
110
|
+
- `--overlap-chars N`: when a section is split, start each part with up to N characters from the end of the part before it (default 0). It is never added inside a code block or table, and never between two different sections.
|
|
111
|
+
- `--prefix-path`: start each chunk's text with its heading path, like `Garden Guide > Planting > Tomatoes`. This often helps search. It counts toward `--max-chars`.
|
|
112
|
+
- `--json`: print one JSON object for scripts and AI agents instead of saving a file.
|
|
113
|
+
|
|
114
|
+
## Known limits
|
|
115
|
+
|
|
116
|
+
- **Sizes are characters, not tokens.** It does not load a tokenizer.
|
|
117
|
+
- **Markdown and plain text only.** PDF, Word and HTML are not read. The paid doc2md turns those into chunks (with page numbers for PDFs).
|
|
118
|
+
- **No folders.** Give it files (your shell can expand `docs/*.md`). The paid doc2md walks whole folders.
|
|
119
|
+
- **Not a full Markdown parser.** A heading inside an HTML block, or an underlined heading that spans more than one line, may be handled wrong.
|
|
120
|
+
- **Overlap uses whole words** from the part before, so it can be a little shorter than you asked for.
|
|
121
|
+
|
|
122
|
+
## Lite vs paid
|
|
123
|
+
|
|
124
|
+
| | md-chunk-lite (free) | [doc2md](https://tidybyte.gumroad.com/l/frlkv) (paid) |
|
|
125
|
+
|---|---|---|
|
|
126
|
+
| Reads | Markdown and text files | PDF, Word (.docx) and HTML |
|
|
127
|
+
| Chunks with the heading path | yes | yes |
|
|
128
|
+
| Line numbers and anchors | yes | no (page numbers for PDFs instead) |
|
|
129
|
+
| Rough token count on each chunk | no | yes |
|
|
130
|
+
| Whole folders, sub-folders too | no | yes |
|
|
131
|
+
| MCP server | yes | no |
|
|
132
|
+
|
|
133
|
+
## Other good free tools
|
|
134
|
+
|
|
135
|
+
Pick what fits you. If you already use LangChain, its `MarkdownHeaderTextSplitter` also splits by heading. [Chonkie](https://github.com/feyninc/chonkie) and [semchunk](https://github.com/isaacus-dev/semchunk) split any text by token count. md-chunk-lite is small, MIT, has no AI or tokenizer parts, gives you line numbers and anchors, and has an MCP server built in.
|
|
136
|
+
|
|
137
|
+
## Use it from Claude Desktop or Cursor (MCP)
|
|
138
|
+
|
|
139
|
+
There is a small free MCP server built in. It needs [uv](https://docs.astral.sh/uv/).
|
|
140
|
+
|
|
141
|
+
Run it by hand to check it starts (it waits quietly for an app to talk to it):
|
|
142
|
+
|
|
143
|
+
```
|
|
144
|
+
uvx md-chunk-lite mcp
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Claude Desktop (`claude_desktop_config.json`) or Cursor (`~/.cursor/mcp.json`):
|
|
148
|
+
|
|
149
|
+
```json
|
|
150
|
+
{
|
|
151
|
+
"mcpServers": {
|
|
152
|
+
"md-chunk-lite": {
|
|
153
|
+
"command": "uvx",
|
|
154
|
+
"args": ["md-chunk-lite", "mcp"]
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`uvx --from md-chunk-lite md-chunk-lite-mcp` starts the same server.
|
|
161
|
+
|
|
162
|
+
Tools (each one takes a file `path` or Markdown `text`):
|
|
163
|
+
|
|
164
|
+
| Tool | What it does | Changes files? |
|
|
165
|
+
|---|---|---|
|
|
166
|
+
| `chunk_markdown` | Splits into chunks. Returns 100 at a time; use `start` for more. | No |
|
|
167
|
+
| `outline_markdown` | Lists the headings with line numbers and anchors. | No |
|
|
168
|
+
| `get_section` | Gets one section by heading or anchor. | No |
|
|
169
|
+
| `save_chunks_jsonl` | Saves the chunks to a `.jsonl` file. | Writes one `.jsonl` file (replaces it if it is there) |
|
|
170
|
+
|
|
171
|
+
None of them use the internet.
|
|
172
|
+
|
|
173
|
+
## For AI agents
|
|
174
|
+
|
|
175
|
+
- **Use when:** you have a Markdown or text file (docs, notes, a README) and need chunks with heading paths and line numbers for search, embeddings or citing sources. Use `outline_markdown` and `get_section` to read just one part of a long file.
|
|
176
|
+
- **Don't use when:** the file is PDF, Word or HTML (convert it first), or you need token-exact sizes.
|
|
177
|
+
- **Input:** a file path or Markdown text, plus `max_chars` (default 1500), `overlap_chars` (default 0) and `prefix_path` (default false).
|
|
178
|
+
- **Output:** chunks with `id`, `source`, `index`, `heading_path`, `heading_level`, `anchor`, `start_line`, `end_line`, `part`, `parts`, `chars`, `text`.
|
|
179
|
+
- CLI exit code is 0 on success and 1 on error (message on stderr, or `{"ok": false, "error": ...}` with `--json`). See also [`llms.txt`](https://github.com/tidybytetools/md-chunk-lite/blob/main/llms.txt).
|
|
180
|
+
|
|
181
|
+
## Python
|
|
182
|
+
|
|
183
|
+
```python
|
|
184
|
+
from md_chunk_lite import chunk_file, chunk_markdown, outline, get_section
|
|
185
|
+
|
|
186
|
+
chunks = chunk_file("guide.md", max_chars=1000)
|
|
187
|
+
for c in chunks:
|
|
188
|
+
print(c["heading_path"], c["start_line"], c["end_line"])
|
|
189
|
+
|
|
190
|
+
install = get_section(open("README.md").read(), heading="Install")
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
The chunker file uses only Python's standard library. Installing with pip also adds the `mcp` package for the MCP server.
|
|
194
|
+
|
|
195
|
+
## Tests
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
pip install "mcp>=1.10,<2"
|
|
199
|
+
python3 -m unittest discover -s tests
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The MCP tests are skipped if `mcp` is not installed.
|
|
203
|
+
|
|
204
|
+
## License
|
|
205
|
+
|
|
206
|
+
MIT. See `LICENSE`.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# md-chunk-lite
|
|
2
|
+
|
|
3
|
+
> Free, MIT-licensed tool that splits Markdown into chunks by heading for RAG, embeddings and search. Every chunk keeps its heading path, GitHub-style anchor, and 1-based start and end line numbers. Deterministic (no AI, no tokenizer). Runs offline. Has a CLI, a Python API and a stdio MCP server.
|
|
4
|
+
|
|
5
|
+
- Install: `pip install md-chunk-lite` (or from GitHub: `pip install git+https://github.com/tidybytetools/md-chunk-lite`)
|
|
6
|
+
- CLI: `md-chunk-lite FILE... [-o out.jsonl | -o -] [--max-chars 1500] [--overlap-chars 0] [--prefix-path] [--outline] [--json]`. Default output is FILE.chunks.jsonl. `-` reads stdin. Exit 0 ok, 1 error.
|
|
7
|
+
- Chunk fields: id, source, index, heading_path (list), heading_level (0 = text before the first heading), anchor, start_line, end_line, part, parts, chars, text.
|
|
8
|
+
- Python: `from md_chunk_lite import chunk_markdown, chunk_file, outline, get_section`.
|
|
9
|
+
- MCP: `uvx md-chunk-lite mcp` (or `uvx --from md-chunk-lite md-chunk-lite-mcp`). Tools: `chunk_markdown(path|text, max_chars, overlap_chars, prefix_path, start, limit)`, `outline_markdown(path|text)`, `get_section(path|text, heading|anchor, include_subsections)` (all read-only), and `save_chunks_jsonl(path, output_path, ...)` (writes one .jsonl file).
|
|
10
|
+
|
|
11
|
+
## Use when
|
|
12
|
+
- You need Markdown docs, notes or READMEs split into chunks that never mix two sections, with line numbers for citing sources.
|
|
13
|
+
- You want just one section of a long Markdown file (get_section) or a map of its headings (outline_markdown).
|
|
14
|
+
|
|
15
|
+
## Don't use when
|
|
16
|
+
- The input is PDF, Word or HTML. The paid doc2md turns PDF, Word and HTML into chunks (page numbers for PDFs) and walks folders: https://tidybyte.gumroad.com/l/frlkv
|
|
17
|
+
- You need sizes measured in tokens. Sizes here are characters.
|
|
18
|
+
|
|
19
|
+
## Links
|
|
20
|
+
- [README](https://github.com/tidybytetools/md-chunk-lite/blob/main/README.md)
|
|
21
|
+
- [Paid doc2md](https://tidybyte.gumroad.com/l/frlkv)
|