# Markdown Review Sidecar Format (MRSF) — Draft [](LICENSE) [](MRSF-v1.0.md) [](https://www.npmjs.com/package/@mrsf/cli) [](https://www.npmjs.com/package/@mrsf/mcp) [](https://www.npmjs.com/package/@mrsf/cli) [](https://www.npmjs.com/package/@mrsf/mcp) [](https://marketplace.visualstudio.com/items?itemName=wictor.mrsf-vscode) [](https://marketplace.visualstudio.com/items?itemName=wictor.mrsf-vscode) [](https://pypi.org/project/mrsf/) [](https://www.npmjs.com/package/@mrsf/markdown-it-mrsf) [](https://www.npmjs.com/package/@mrsf/marp-mrsf) [](https://www.npmjs.com/package/@mrsf/marked-mrsf) [](https://www.npmjs.com/package/@mrsf/rehype-mrsf) [](https://modelcontextprotocol.io) **Markdown Review Sidecar Format (MRSF)**, also known as **Sidemark**, is a portable, version-controlled, and machine-actionable way to store review comments *outside* Markdown files. 🌐 [sidemark.org](https://sidemark.org) · 💻 [VS Code Extension](https://marketplace.visualstudio.com/items?itemName=wictor.mrsf-vscode) This makes: - Markdown docs clean and uncluttered - Review history persist across edits - Automated review tools and AI agents/skills able to reason about comments reliably ## 🧠 What Problem This Solves Markdown workflows today struggle with durable, context-aware review comments: - Inline comments can’t move with the text - GitHub/GitLab reviews vanish with edits - Automated agents (LLMs, bots) have no structured API for feedback MRSF solves this with **sidecar files** that hold review metadata separate from content and a CLI/MCP interface for tooling. ## 🚀 Features - Standardized sidecar format for Markdown reviews - Anchors with line/span + fallback matching (`selected_text`) - Re-anchoring after edits using configurable strategies - JSON Schema for validation - CLI tools for validation, re-anchoring, status checks - MCP server for integrations with LLMs and assistant clients - Python CLI & SDK (`pip install mrsf`) — 1:1 port of the Node.js CLI - Rendering plugins for Marp, Marked, markdown-it, and rehype/unified ecosystems - Interactive editor integrations for VS Code, Monaco, Milkdown/Crepe, and experimental Tiptap hosts ## 📄 Specification The full specification is available in [MRSF-v1.0.md](MRSF-v1.0.md). ## 🔧 Quick Start ### Install ```bash # Node.js npm install -g @mrsf/cli # Python pip install mrsf ``` ### Typical workflow ``` bash # create a sidecar for a Markdown file mrsf init docs/architecture.md # add a comment anchored at line 12 mrsf add docs/architecture.md -l 12 "Add more detail about this architecture." # check for issues mrsf validate # after the document changes mrsf reanchor # see comment health mrsf status ``` You can also attach tool-specific extension fields when creating comments. The public SDKs and MCP server accept these as key/value maps, and they are stored on disk as flat `x_*` fields: ```bash mrsf add docs/architecture.md \ --author "review-bot" \ --text "Needs a second pass" \ --line 12 \ --ext x_source=review-bot \ --ext x_score=0.91 \ --ext 'x_labels=["needs-review","docs"]' ``` See the full CLI documentation in [`cli/README.md`](cli/README.md), or run `mrsf --help`. ## 📦 Examples Minimal sidecar (`.review.yaml`) next to the Markdown): ``` yaml mrsf_version: "1.0" document: docs/architecture.md comments: - id: abc123 author: Jane Doe timestamp: '2026-03-02T18:22:59Z' text: "Can you clarify this section?" resolved: false line: 9 ``` Advanced example with exact span: ```yaml - id: def456 author: Jane Doe timestamp: '2026-03-02T18:24:51Z' text: "Is this phrasing accurate?" type: question resolved: false line: 12 end_line: 12 start_column: 42 end_column: 73 selected_text: "While many concepts are represented" ``` More examples: see the [`examples`](/examples/) folder. ## 🛠 MCP Server You can run MRSF as an MCP (Model Context Protocol) server for LLM/assistant integrations. Install: ```bash npm install -g @mrsf/mcp ``` Example (Claude Desktop config): ```json { "mcpServers": { "mrsf": { "command": "npx", "args": ["-y", "@mrsf/mcp"] } } } ``` Servers expose resources like: - `mrsf://sidecar/{path}` - `mrsf://comment/{path}/{id}` - `mrsf://anchors/{path}` See the full MCP server documentation in [`mcp/README.md`](mcp/README.md). ## 💻 VS Code Extension **[Sidemark for VS Code](https://marketplace.visualstudio.com/items?itemName=wictor.mrsf-vscode)** brings MRSF review comments directly into your editor — gutter icons, inline previews, hover cards, a sidebar panel, and automatic reanchoring on save. Install from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=wictor.mrsf-vscode) or search for **"Sidemark"** in the VS Code Extensions view. ## 🧪 Monorepo Tests All TypeScript/Vitest packages can now be run from the repository root: ```bash npm install npm test ``` For watch mode or coverage from the root: ```bash npm run test:watch npm run test:coverage ``` The root Vitest project aggregates: - `cli/` - `mcp/` - `plugins/shared/` - `plugins/markdown-it/` - `plugins/monaco/` - `plugins/rehype/` - `vscode/` ## 🐍 Python CLI & SDK A full Python port of the CLI and library, installable via pip: ```bash pip install mrsf ``` Same 9 commands, same library API, same 134 tests: ```python import mrsf doc = mrsf.parse_sidecar("README.md.review.yaml") for comment in doc.comments: print(f"{comment.author}: {comment.text}") result = mrsf.validate(doc) ``` Python uses the same explicit extension-map contract when adding comments: ```python opts = mrsf.AddCommentOptions( author="review-bot", text="Needs a second pass", line=12, extensions={ "x_source": "review-bot", "x_score": 0.91, "x_labels": ["needs-review", "docs"], }, ) ``` See [`python/README.md`](python/README.md) for the full SDK reference. ## 🎨 Rendering Plugins Render MRSF review comments directly in Markdown output as badges, highlights, and tooltips. ### markdown-it Plugin For VitePress, markdown-it, and any markdown-it-based renderer: ```bash npm install @mrsf/markdown-it-mrsf ``` ```js import MarkdownIt from "markdown-it"; import { mrsfPlugin } from "@mrsf/markdown-it-mrsf"; const md = new MarkdownIt(); md.use(mrsfPlugin, { sidecarPath: "doc.md.review.yaml" }); ``` See [`plugins/markdown-it/README.md`](plugins/markdown-it/README.md). ### Marp Plugin For Marpit and Marp presentation pipelines: ```bash npm install @mrsf/marp-mrsf ``` ```js import { Marpit } from "@marp-team/marpit"; import { mrsfPlugin } from "@mrsf/marp-mrsf"; const marpit = new Marpit(); marpit.use(mrsfPlugin, { comments: sidecarData, interactive: true }); ``` The plugin adds `data-mrsf-page` metadata to rendered page containers and also accepts vendor-only `x_page` comment hints when a presentation-level anchor is more useful than a line anchor. See [`plugins/marp/README.md`](plugins/marp/README.md). ### Marked Plugin For Marked-based renderers in Node.js or the browser: ```bash npm install marked @mrsf/marked-mrsf ``` ```js import { Marked } from "marked"; import { markedMrsf } from "@mrsf/marked-mrsf"; const parser = new Marked(); parser.use(markedMrsf({ sidecarPath: "doc.md.review.yaml" })); ``` See [`plugins/marked/README.md`](plugins/marked/README.md). ### rehype Plugin For Astro, Next.js MDX, Docusaurus, and the unified ecosystem: ```bash npm install @mrsf/rehype-mrsf ``` ```js import { unified } from "unified"; import remarkParse from "remark-parse"; import remarkRehype from "remark-rehype"; import { rehypeMrsf } from "@mrsf/rehype-mrsf"; import rehypeStringify from "rehype-stringify"; const file = await unified() .use(remarkParse) .use(remarkRehype) .use(rehypeMrsf, { sidecarPath: "doc.md.review.yaml" }) .use(rehypeStringify) .process(markdown); ``` See [`plugins/rehype/README.md`](plugins/rehype/README.md). ## ✍️ Interactive Editor Integrations MRSF also ships editor-native integrations when you want the review workflow inside a live editing surface instead of rendered HTML. ### Monaco Plugin For Monaco-based editors in browser and desktop apps: ```bash npm install @mrsf/monaco-mrsf monaco-editor ``` See [`plugins/monaco/README.md`](plugins/monaco/README.md). ### Tiptap Plugin (Experimental) For browser-hosted Tiptap editors with inline highlights, gutters, and an explicit-save review workflow: ```bash npm install @mrsf/tiptap-mrsf @tiptap/core @tiptap/starter-kit ``` See [`plugins/tiptap/README.md`](plugins/tiptap/README.md). ### Milkdown + Crepe Plugin The `@mrsf/milkdown-mrsf` package runs the same MRSF review controller in both direct Milkdown editors and the higher-level Crepe shell. It covers sidecar load/save/reload/reanchor flows, inline anchors, gutter overlays, thread tooltips, and selection-based comment actions through a browser host adapter. Try the demo: ```bash cd examples npm install npm run demo:milkdown ``` Then open the printed local Vite URL and navigate to `/` to switch between direct Milkdown and Crepe while they share the same review runtime. See [`plugins/milkdown/README.md`](plugins/milkdown/README.md). ## Stability & Versioning The MRSF specification is currently **v1.0 Draft**. Published packages follow [Semantic Versioning](https://semver.org/); while packages remain pre-1.0, minor releases may include breaking changes and consumers should read package changelogs before upgrading. Package changelogs: - [`@mrsf/cli`](cli/CHANGELOG.md) - [`@mrsf/mcp`](mcp/CHANGELOG.md) - [`@mrsf/markdown-it-mrsf`](plugins/markdown-it/CHANGELOG.md) - [`@mrsf/rehype-mrsf`](plugins/rehype/CHANGELOG.md) Tools target `mrsf_version` `"1.0"`. Consumers SHOULD tolerate unknown future minor versions and unknown `x_`-prefixed extension fields by preserving them when reading and writing sidecars. Consumers SHOULD warn, rather than silently proceed, when they encounter an unknown major version. ## 🧪 Status **Draft**: this specification and tooling are open for feedback and improvement. File issues or pull requests with suggestions. ## ❤️ Contributing We welcome: - review of the spec - implementation feedback on the CLI/MCP/Python SDK - integration examples with editors, renderers, and bots | Package | Path | Install | |---------|------|---------| | CLI & library | [`cli/`](cli/) | `npm install @mrsf/cli` | | MCP server | [`mcp/`](mcp/) | `npm install @mrsf/mcp` | | VS Code extension | [`vscode/`](vscode/) | [Marketplace](https://marketplace.visualstudio.com/items?itemName=wictor.mrsf-vscode) | | Python CLI & SDK | [`python/`](python/) | `pip install mrsf` | | Marked plugin | [`plugins/marked/`](plugins/marked/) | `npm install @mrsf/marked-mrsf` | | Marp plugin | [`plugins/marp/`](plugins/marp/) | `npm install @mrsf/marp-mrsf` | | markdown-it plugin | [`plugins/markdown-it/`](plugins/markdown-it/) | `npm install @mrsf/markdown-it-mrsf` | | Monaco plugin | [`plugins/monaco/`](plugins/monaco/) | `npm install @mrsf/monaco-mrsf` | | Milkdown + Crepe plugin | [`plugins/milkdown/`](plugins/milkdown/) | See package README | | rehype plugin | [`plugins/rehype/`](plugins/rehype/) | `npm install @mrsf/rehype-mrsf` | | Tiptap plugin (experimental) | [`plugins/tiptap/`](plugins/tiptap/) | `npm install @mrsf/tiptap-mrsf` | | Documentation | [`docs/`](docs/) | [sidemark.org](https://sidemark.org) | See [`CONTRIBUTING.md`](CONTRIBUTING.md) > **Disclaimer** > MRSF is a personal open‑source project. > It is **not affiliated with, endorsed by, or an official standard of Microsoft**. > Any internal experimentation does not imply product adoption. ## 📄 License [`MIT`](LICENSE)