{
  "markdown": "# md-vision MCP server\n\nstdio MCP server with two read-only tools for agentic RAG over markdown documentation:\n\n- **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.\n- **index_md** — return a compact heading index for a file, URL, or folder of markdown files. Used to dynamically index files for targeted reads.\n\nTypical flow: call `index_md` to discover headings and structure, then `read_md_with_images` on the sections you need.\n\n## Install: MCP client configuration\n\nPublished package: [md-vision on npm](https://www.npmjs.com/package/md-vision)\n\nIn your agent config (`.agents/mcp.json` or similar), point your MCP host at the server. Example:\n\n```json\n{\n  \"mcpServers\": {\n    \"md-vision\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"md-vision\",\n        \"--allow-path\",\n        \"/absolute/path/to/docs\",\n        \"--allow-domain\",\n        \"none\"\n      ]\n    }\n  }\n}\n```\n\n**With remote markdown** (allow all HTTP(S) hosts, or list specific domains):\n\n```json\n{\n  \"mcpServers\": {\n    \"md-vision\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"md-vision\",\n        \"--allow-path\",\n        \"/absolute/path/to/docs\",\n        \"--allow-domain\",\n        \"all\"\n      ]\n    }\n  }\n}\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"md-vision\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"md-vision\",\n        \"--allow-path\",\n        \"/absolute/path/to/docs\",\n        \"--allow-domain\",\n        \"raw.githubusercontent.com\"\n      ]\n    }\n  }\n}\n```\n\nThe server exits on startup if `--allow-path` or `--allow-domain` is omitted.\n\nRestart the MCP host after changing configuration.\n\n### Restricting allowed paths and domains\n\n| Flag | Required | Effect |\n|------|----------|--------|\n| `--allow-path <dir>` | Yes (at least one) | Local files must resolve under one of the allowed directories (repeatable). |\n| `--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`). |\n\nEquivalent forms: `--allow-path=/path`, `--allow-domain=host.example`, `--allow-domain=all`, `--allow-domain=none`.\n\nDo 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.\n\n### Requirements\n\n- Node.js 20+\n\n## Tools\n\n### read_md_with_images\n\nRead a markdown file and inline referenced images as MCP image content.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `uri` | string | Local path or `http(s)://` URL |\n| `section` | string, optional | Exact heading to read, e.g. `## Introduction` (used when matched; otherwise falls back to `line_range`) |\n| `line_range` | `[start, end]`, optional | Inclusive 1-based document line range (used when `section` is omitted or not found) |\n| `max_images` | integer, optional | Max images to inline (default `10`, max `50`) |\n\n**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.\n\n**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.\n\n### index_md\n\nIndex headings for navigation before targeted reads.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `uri` | string | Markdown file, `http(s)://` URL, or local folder |\n\n**Returns:** Markdown string. For each file:\n\n1. YAML frontmatter when present.\n2. A fenced `tsv` code block with columns: `heading`, `line_start`, `n_images`, `char_count`.\n\nEach file is wrapped in:\n\n```xml\n<file path=\"...\" lines=X chars=Y>\n...\n</file>\n```\n\nFolder `uri` values are scanned recursively for `*.md` / `*.markdown` in stable sorted order. Headings inside fenced code blocks are not indexed.\n\n## Note on deploying agents with this MCP server\n\nstdio MCP servers run as subprocesses of the agent runtime that invokes them. There are two deployment patterns commonly used:\n\n- **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.\n- **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.\n\n## Benchmark (WIP)\n\nSee [`benchmark/`](benchmark/) for the MMLongBench-Doc A/B harness comparing\nfilesystem-only agentic RAG against the same agent with `md-vision` MCP tools.\n\n## Standalone indexing\n\n`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.\n\nInstall the package:\n\n```bash\nnpm install md-vision\n```\n\n### Index markdown text\n\nUse `indexMarkdownText` when you already have markdown content in memory.\n\n```ts\nimport { indexMarkdownText } from \"md-vision\";\n\nconst markdown = `# Guide\n\nIntro text.\n\n## Setup\n\n![diagram](./setup.png)\n`;\n\nconst index = indexMarkdownText(markdown);\n\nconsole.log(index.rows);\n```\n\nExample result:\n\n```ts\n[\n  {\n    heading: \"# Guide\",\n    lineStart: 1,\n    imageCount: 1,\n    charCount: 42\n  },\n  {\n    heading: \"## Setup\",\n    lineStart: 5,\n    imageCount: 1,\n    charCount: 24\n  }\n]\n```\n\n### Index a file\n\nUse `indexMarkdownFile` to load and index a local markdown file.\n\n```ts\nimport { indexMarkdownFile } from \"md-vision\";\n\nconst index = await indexMarkdownFile(\"./docs/guide.md\");\n\nawait saveToVectorStoreMetadata({\n  path: index.path,\n  frontmatter: index.frontmatter,\n  headings: index.rows,\n});\n```\n\n### Index a folder\n\nUse `indexMarkdownFolder` to recursively index `*.md` and `*.markdown` files in stable sorted order.\n\n```ts\nimport { indexMarkdownFolder } from \"md-vision\";\n\nconst files = await indexMarkdownFolder(\"./docs\");\n\nfor (const file of files) {\n  console.log(file.path, file.rows);\n}\n```\n\n### Output shape\n\nEach indexed file returns structured data:\n\n```ts\ntype MarkdownFileIndex = {\n  path?: string;\n  frontmatter: string;\n  lineCount: number;\n  charCount: number;\n  rows: HeadingIndexRow[];\n};\n\ntype HeadingIndexRow = {\n  heading: string;\n  lineStart: number;\n  imageCount: number;\n  charCount: number;\n};\n```\n\nHeadings inside fenced code blocks are ignored because indexing uses the markdown AST rather than regex matching.\n",
  "bytes": 6881,
  "sha": "dce65b5d98d29199f6d5853a008fd40add60214f00d528519be2ce69b734de3a",
  "repo_slug": "japlete/md-vision-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_japlete_md_vision_1cabd8c6/readme"
}