japlete/md-vision-mcp

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
In your agent config (.agents/mcp.json or similar), point your MCP host at the server. Example:
**With remote markdown** (allow all HTTP(S) hosts, or list specific domains):
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 | Yes (at least one) | Local files must resolve under one of the allowed directories (repeatable). |
| --allow-domain | 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 tags.
index_md
Index headings for navigation before targeted reads.
| Parameter | Type | Description |
|-----------|------|-------------|
| uri | string | Markdown file, http(s):// URL, or local folder |