md-vision
Read markdown with inlined images and index headings for agentic RAG workflows.
Open source Open in the app JSON README (API)
About
Read markdown with inlined images and index headings for agentic RAG workflows.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- japlete
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.1
- Stars
- 1
- Last push
- 2026-06-21T16:39:38Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:14
- Updated
- 2026-08-29 04:00:14
- Origin id
io.github.japlete/md-vision
README
# md-vision MCP server
stdio MCP server with two read-only tools for agentic RAG over markdown documentation:
- **read_md_with_images** — return markdown with referenced images as interleaved image blocks. Avoids an extra tool call for each image to read. Optionally scoped to a specific section or line range.
- **index_md** — return a compact heading index for a file, URL, or folder of markdown files. Used to dynamically index files for targeted reads.
Typical flow: call `index_md` to discover headings and structure, then `read_md_with_images` on the sections you need.
## Install: MCP client configuration
Published package: [md-vision on npm](https://www.npmjs.com/package/md-vision)
In your agent config (`.agents/mcp.json` or similar), point your MCP host at the server. Example:
```json
{
"mcpServers": {
"md-vision": {
"command": "npx",
"args": [
"md-vision",
"--allow-path",
"/absolute/path/to/docs",
"--allow-domain",
"none"
]
}
}
}
```
**With remote markdown** (allow all HTTP(S) hosts, or list specific domains):
```json
{
"mcpServers": {
"md-vision": {
"command": "npx",
"args": [
"md-vision",
"--allow-path",
"/absolute/path/to/docs",
"--allow-domain",
"all"
]
}
}
}
```
```json
{
"mcpServers": {
"md-vision": {
"command": "npx",
"args": [
"md-vision",
"--allow-path",
"/absolute/path/to/docs",
"--allow-domain",
"raw.githubusercontent.com"
]
}
}
}
```
The server exits on startup if `--allow-path` or `--allow-domain` is omitted.
Restart the MCP host after changing configuration.
### Restricting allowed paths and domains
| Flag | Required | Effect |
|------|----------|--------|
| `--allow-path <dir>` | Yes (at least one) | Local files must resolve under one of the allowed directories (repeatable). |
| `--allow-domain <host>` | Yes (at least one) | Controls HTTP(S) access. Use `all` to allow any host, `none` to disable URLs (local files only), or list specific hosts (repeatable; suffix match supported, e.g. `example.com` allows `docs.example.com`). |
Equivalent forms: `--allow-path=/path`, `--allow-domain=host.example`, `--allow-domain=all`, `--allow-domain=none`.
Do not pass a bare `*` as a separate shell argument — the shell expands it to filenames in the current directory. Use `all` or `--allow-domain=all` instead.
### Requirements
- Node.js 20+
## Tools
### read_md_with_images
Read a markdown file and inline referenced images as MCP image content.
| Parameter | Type | Description |
|-----------|------|-------------|
| `uri` | string | Local path or `http(s)://` URL |
| `section` | string, optional | Exact heading to read, e.g. `## Introduction` (used when matched; otherwise falls back to `line_range`) |
| `line_range` | `[start, end]`, optional | Inclusive 1-based document line range (used when `section` is omitted or not found) |
| `max_images` | integer, optional | Max images to inline (default `10`, max `50`) |
**Returns:** MCP content array — alternating `text` and `image` blocks (PNG, base64) in document order; frontmatter preserved in the leading text. Before each inlined image, a short `text` block carries the resolved image URL (omitted for `data:` URIs and other long references). Images beyond `max_images` stay as markdown image syntax in text.
**URI forms:** local filesystem paths and `http(s)://` URLs. Local paths must fall under a configured `--allow-path` directory. Relative image paths resolve against the markdown file location or document URL. Images may use markdown `` syntax or HTML `<img src="...">` tags.
### index_md
Index headings for navigation before targeted reads.
| Parameter | Type | Description |
|-----------|------|-------------|
| `uri` | string | Markdown file, `http(s)://` URL, or local folder |
**Returns:** Markdown string. For each file:
1. YAML frontmatter when present.
2. A fenced `tsv` code block with columns: `heading`, `line_start`, `n_images`, `char_count`.
Each file is wrapped in:
```xml
<file path="..." lines=X chars=Y>
...
</file>
```
Folder `uri` values are scanned recursively for `*.md` / `*.markdown` in stable sorted order. Headings inside fenced code blocks are not indexed.
## Note on deploying agents with this MCP server
stdio MCP servers run as subprocesses of the agent runtime that invokes them. There are two deployment patterns commonly used:
- **Agent-in-sandbox** (runtime shares the agent’s filesystem): the server can read docs in-place; scope `--allow-path` to the documentation tree you intend to expose.
- **Sandbox-as-tool** (runtime filesystem differs from the tool sandbox): the MCP process usually runs in the runtime environment, so markdown must be copied or synced where the server can read it.
## Benchmark (WIP)
See [`benchmark/`](benchmark/) for the MMLongBench-Doc A/B harness comparing
filesystem-only agentic RAG against the same agent with `md-vision` MCP tools.
## Standalone indexing
`md-vision` can also be used as a library when you want to index markdown outside an MCP host — for example in an offline preprocessing pipeline for agentic RAG.
Install the package:
```bash
npm install md-vision
```
### Index markdown text
Use `indexMarkdownText` when you already have markdown content in memory.
```ts
import { indexMarkdownText } from "md-vision";
const markdown = `# Guide
Intro text.
## Setup
`;
const index = indexMarkdownText(markdown);
console.log(index.rows);
```
Example result:
```ts
[
{
heading: "# Guide",
lineStart: 1,
imageCount: 1,
charCount: 42
},
{
heading: "## Setup",
lineStart: 5,
imageCount: 1,
charCount: 24
}
]
```
### Index a file
Use `indexMarkdownFile` to load and index a local markdown file.
```ts
import { indexMarkdownFile } from "md-vision";
const index = await indexMarkdownFile("./docs/guide.md");
await saveToVectorStoreMetadata({
path: index.path,
frontmatter: index.frontmatter,
headings: index.rows,
});
```
### Index a folder
Use `indexMarkdownFolder` to recursively index `*.md` and `*.markdown` files in stable sorted order.
```ts
import { indexMarkdownFolder } from "md-vision";
const files = await indexMarkdownFolder("./docs");
for (const file of files) {
console.log(file.path, file.rows);
}
```
### Output shape
Each indexed file returns structured data:
```ts
type MarkdownFileIndex = {
path?: string;
frontmatter: string;
lineCount: number;
charCount: number;
rows: HeadingIndexRow[];
};
type HeadingIndexRow = {
heading: string;
lineStart: number;
imageCount: number;
charCount: number;
};
```
Headings inside fenced code blocks are ignored because indexing uses the markdown AST rather than regex matching.