md-vision

Name: md-vision
Author: japlete

by japlete

Overview Schema Source Related Servers Discussions Admin

Python

Local

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

In your agent config (.agents/mcp.json or similar), point your MCP host at the server. Example:

{
  "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):

{
  "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"
      ]
    }
  }
}

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+

Related MCP server: mcp-server-markdown

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:

YAML frontmatter when present.
A fenced tsv code block with columns: heading, line_start, n_images, char_count.

Each file is wrapped in:

<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/ 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:

npm install md-vision

Index markdown text

Use indexMarkdownText when you already have markdown content in memory.

import { indexMarkdownText } from "md-vision";

const markdown = `# Guide

Intro text.

## Setup

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

const index = indexMarkdownText(markdown);

console.log(index.rows);

Example result:

[
  {
    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.

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.

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:

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.

Available Tools

2 tools

index_mdIndex markdown headingsA

Read-onlyIdempotent

Index headings in a markdown file, URL, or local folder. Returns frontmatter (if any) and a TSV table of headings, line_start, n_images, char_count; use read_md_with_images to read specific content.

ParametersJSON Schema

Name	Required	Description	Default
`uri`	Yes	Local path, HTTP(S) URL, or local folder to index for markdown headings.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds detail about return format (frontmatter, TSV table) without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first clearly states the purpose, second adds output details and sibling distinction. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter, full annotations, and no output schema, the description covers purpose, usage guidelines, and return type adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage for the single parameter 'uri' with a clear description. The tool description does not add significant new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states verb 'Index' on resource 'markdown headings', specifies sources (file, URL, folder), and differentiates from sibling tool read_md_with_images by indicating the latter is for reading content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly indicates when to use this tool (to index headings) and provides an alternative for reading content: 'use read_md_with_images to read specific content.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_md_with_imagesRead markdown with imagesA

Read-onlyIdempotent

Read a markdown file or selected section/range and return the markdown with interleaved image blocks. Use section for an exact heading; if it is missing, line_range is used when provided. Optionally use index_md first to discover headings.

ParametersJSON Schema

Name	Required	Description
`uri`	Yes	Local path or HTTP(S) URL of the markdown file to read.
`section`	No	Exact heading to read, including marker, for example '## Introduction'. When matched, takes precedence over line_range.
`line_range`	No	Inclusive 1-based document line range, for example [1, 10]. Used when section is omitted or not found.
`max_images`	No	Maximum referenced images to inline as image blocks. Defaults to 10.

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate the tool is read-only, non-destructive, idempotent, and open-world. The description adds behavioral detail: it interleaves image blocks and clarifies parameter precedence. However, it does not describe the output format in detail or error behavior, which would add further transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences that cover purpose and usage guidance without redundancy. Every sentence contributes meaningful information, and it is well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers input parameters and behavior adequately. It mentions optional indexing with index_md. However, there is no output schema, and the description could be more specific about the output format and error handling, leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema already documents each parameter. The description adds value by explaining the interaction between section and line_range (precedence) and hints at using index_md for heading discovery, which is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads a markdown file and returns it with interleaved image blocks. It specifies the resource (markdown file), action (read with images), and differentiates from the sibling tool index_md by mentioning its optional use for heading discovery.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to use section vs line_range parameters, including the precedence rule. It also recommends using index_md first to discover headings, providing clear context on tool selection and parameter use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

2 tool updatesv0.1.0Jun 21, 2026
- First observedindex_md
- First observedread_md_with_images

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored 2026-06-21 15:31 across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one indexes headings and metadata, the other reads content with images. No overlap in functionality.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (index_md, read_md_with_images) using snake_case, making them predictable.

Tool Count2/5

With only 2 tools, the server feels underdeveloped for typical markdown operations. While the tools are focused, a broader scope would justify more tools.

Completeness2/5

The server covers indexing and reading with images, but lacks essential operations like editing, deleting, or creating markdown content, leaving significant gaps.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

fetch-extract
io.github.CedricKouma
MCP server (stdio): fetch web pages as clean readable markdown via the AgentForge API
Browser Automation Web Scraping
2
Mdkit A
online.mdkit
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Developer Tools RAG Systems Data Platforms
31
skim A
dev.workers.perch-app.skim
URL to Markdown or structured JSON (schema.org/OG); renders SPA; batch reads. No signup/key.
Browser Automation Web Scraping
11
trip2g B
io.github.trip2g
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
RAG Systems Note Taking Search
11238

Related MCP Servers

Markdown to HTML MCP Server
Developer Tools Content Management Systems App Automation
1623311678
A
license
D
quality
D
maintenance
An MCP server that converts Markdown to HTML, supporting both stdio and HTTP interfaces for easy integration with Cursor and other MCP clients.
Updated a year ago (2025-06-14 18:03 UTC)
1
8 npm
MIT
mcp-server-markdown
Developer Tools Documentation Access File Systems
ofershap
A
license
A
quality
D
maintenance
MCP server for markdown files — search, extract sections, list headings, find code blocks across docs.
Updated a month ago (2026-08-10 07:38 UTC)
6
135 npm
5
MIT
SeekLink
Knowledge & Memory RAG Systems Search
simonsysun
A
license
Not graded
quality
B
maintenance
Local-first Markdown vault retrieval for agents. Read-only MCP stdio server exposing search, get, status, and doctor over Obsidian-compatible Markdown with hybrid BM25/vector/wikilink/title retrieval and first-class CJK support.
Updated 3 months ago (2026-06-08 00:35 UTC)
11
MIT
okf-mcp-server
Knowledge & Memory Documentation Access
dddpaul
F
license
Not graded
quality
B
maintenance
Reusable, read-only MCP server that exposes a repo's knowledge files (backlog docs, decisions, design notes) as MCP resources over stdio.
Updated 13 days ago (2026-09-01 17:33 UTC)
-

md-vision MCP server

Install: MCP client configuration

Restricting allowed paths and domains

Requirements

Tools

read_md_with_images

index_md

Note on deploying agents with this MCP server

Benchmark (WIP)

Standalone indexing

Index markdown text

Index a file

Index a folder

Output shape

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Markdown to HTML MCP Server

mcp-server-markdown

SeekLink

okf-mcp-server