What can you do with this server?

The md-redline server enables two-way inline review and commenting on markdown files between humans and AI agents. It provides four core tools: * mdr_request_review: Open markdown files for human review. The agent hands off a document to the user and waits for feedback (batches of inline comments). The agent can re-poll with a session ID to continue receiving feedback batch by batch. * mdr_review: Post inline anchored comments and/or replies to existing comments on markdown files (non-blocking). Comments appear in the browser UI anchored to exact text, allowing agents to critique, annotate, or respond to human-written documents. * mdr_wait: Block until the user finishes engaging with a review session (clicks "Done"). Must be called after mdr_review; re-callable up to 90 seconds per call. Afterward, the agent can re-read the file to pick up replies, edits, and deletions. * mdr_ask: Post one or more clarifying questions anchored to specific text inside an active session. Blocks until the user answers all questions, enabling interactive clarification without guessing at ambiguous instructions. Key characteristics: * Comments are stored directly in the markdown file as invisible HTML markers — no sidecar files or external database. * Sessions support multiple files at once. * An optional resolve workflow (enableResolve) adds explicit open/resolved states to comments. * Each tool call includes an author field to distinguish feedback from different agents in multi-agent setups.

Which integrations are available for this server?

Allows Google Gemini agents to request human review of markdown files, review human-written docs, and ask anchored questions using md-redline. Allows OpenAI Codex agents to request human review of markdown files, review human-written docs, and ask anchored questions using md-redline.

de en es ja ko ru zh

md-redline

by dejuknow

Overview Schema Related Servers Score Discussions

TypeScript

Local

md-redline

npm version

Inline review comments for markdown specs, prompts, and design docs.

Highlight text in a rendered document, leave comments, and your AI agent can read and address them directly. Comments are stored as invisible HTML markers in the .md file itself. No sidecar files, no database, no external service. The markdown file stays the source of truth.

With the built-in MCP server, review runs in both directions. Your agent can request your review mid-task and pause until you send your feedback, or review a doc you wrote and leave anchored comments for you. Either way: no copy-paste, no context switching.

md-redline screenshot

See the full review workflow in about 30 seconds:

https://github.com/user-attachments/assets/8b9b3546-a895-42e1-b3cc-5ee5b2c00398

Works with Claude Code, Claude Desktop, Codex CLI, Gemini CLI, and any other MCP client that supports stdio servers. As Sean Grove argues in specs are the new code, specs are becoming the primary unit of work in agentic development. mdr gives that workflow review tooling closer to code review.

Quick start

Prerequisite: Node 20 or newer.

npx md-redline /path/to/spec.md

This starts the local app if needed and opens it in your browser.

Or install globally:

npm install -g md-redline
mdr /path/to/spec.md        # Open a file
mdr /path/to/dir             # Open a directory
mdr --stop                   # Stop the running server

md-redline also works as an alias for mdr.

That gives you the viewer and commenting. The agent integration (reviews in both directions, anchored questions) comes from the MCP server, registered in the next section.

Related MCP server: md-annotate

Updating

mdr checks npm once a day (from its local server, never blocking anything) and shows a small notice in the viewer and the terminal when a new version is out. Upgrading is one command:

npm install -g md-redline@latest

The running server restarts itself on the next mdr invocation after an upgrade. To disable update checks entirely, set NO_UPDATE_NOTIFIER=1 (or run in CI, which is auto-detected). Note this is a presence check, following the ecosystem convention: any value, even 0 or empty, disables the checks.

MCP setup

Claude Code or Claude Desktop

mdr mcp install                   # register with both clients (default)
mdr mcp install --claude-code     # just Claude Code (via `claude mcp add`)
mdr mcp install --claude-desktop  # just Claude Desktop (JSON config file)

Codex CLI

codex mcp add md-redline -- mdr mcp

Gemini CLI

gemini mcp add --scope user md-redline mdr mcp

The --scope user flag is important. Gemini defaults to per-project scope, which only registers mdr for the current directory.

Other MCP clients

Add this server entry to your client's MCP config file:

{
  "mcpServers": {
    "md-redline": {
      "command": "mdr",
      "args": ["mcp"]
    }
  }
}

Prerequisite: mdr must be on your PATH (e.g. via npm install -g md-redline). If your client spawns subprocesses without inheriting your shell's PATH, use the absolute path from which mdr as the command value.

After installing, restart your MCP client; most clients only discover new servers at launch. To verify, ask your agent "what mdr tools do you have?" and it should list mdr_request_review, mdr_comment, mdr_ask, and mdr_wait. (mdr_comment was called mdr_review before 0.9; the old name still works if you have it saved in a prompt, but agents are no longer offered it.)

Review workflow

With MCP registered, review runs in both directions. Pick by who is giving the feedback:

	You review the agent's doc	The agent reviews your doc
Typical moment	The agent just drafted or edited a spec; you want to mark it up before it continues	You wrote a PRD (or received one) and want a critique
What you say	"Let me review specs/feature-x.md in mdr before you continue."	"Use mdr to review prd.md and leave comments."
Who comments	You	The agent
How it ends	You click Send & finish	You click End review

1. You review the agent's doc

The common flow right after an agent drafts a document. Tell the agent:

"Let me review docs/specs/feature-x.md in mdr before you continue."

The agent calls mdr_request_review and pauses. mdr opens the file, you highlight text and leave comments, then click Send N comments. The agent receives your feedback as a structured prompt and starts addressing your comments. You can keep sending follow-up batches while it works; Send N & finish sends the last batch and closes the loop. The review is opt-in per request. The agent only pauses when you ask for it.

2. The agent reviews your doc

The reverse direction, for docs the agent did not just write: your own draft, a teammate's PRD, a spec from another repo. Tell the agent:

"Use mdr to review prd.md and leave comments."

The agent calls mdr_comment. Its findings land as inline comments anchored to the exact text, and the browser opens so you can read them as they arrive. The agent then waits (via mdr_wait) while you work through the feedback: reply on any card, edit the doc, delete comments you disagree with. When you are done, click End review in the banner. That click is the signal for the agent to re-read the file and pick up your replies and edits, so the session stays open until you press it. The agent is not stuck; it is listening.

https://github.com/user-attachments/assets/a695017d-ed59-4fe8-8a29-e5306dab788c

Either direction: the agent can ask you questions

Inside any active session, the agent can hit a fork where your answer changes what it should do next. Rather than guessing, it can call mdr_ask to post anchored questions into the doc and block until you answer:

You get a toast with a View button, a banner chip ("N questions awaiting your reply"), and a "(N questions)" tab title, so you notice even from another window.
Each question is a normal comment card anchored to the sentence it is about. Reply right on the card.
The moment every question has an answer, the agent unblocks with your reply text. No End review needed.

This shines during hand-offs. Leave a comment like "this conflicts with what we decided, fix it," and instead of guessing, the agent asks "which decision: per-seat or flat-rate?" anchored where it matters. You can also request the pattern directly:

"Review prd.md with mdr. For your top 2 open questions, use mdr_ask and incorporate my answers before summarizing."

Questions and reviews survive in the file as ordinary comment markers, so nothing is lost if a session ends early: the agent is always told to re-read the file.

Without MCP

Open a markdown file with mdr /path/to/spec.md.
Highlight text and leave inline comments.
Copy the hand-off prompt.
Paste the prompt into your AI agent.
The agent edits the file, addresses the feedback, and removes the comment markers it handled.
Review the result in diff view.

Optional: resolve workflow

Enable resolve mode in Settings for human review with explicit open and resolved states.

Who this is for

People writing specs, prompts, or design docs locally with file-based AI agents
Teams reviewing docs before they are committed or sent out for wider review
Anyone in a human + agent editing loop who wants structured inline feedback in plain files

Non-goals

Not a collaborative multi-user editing tool.
Not a replacement for GitHub PR reviews (use those once the file is in git).
Not designed for untrusted content. This is a local dev tool for your own files.

How comments are stored

Comments are stored as invisible HTML markers directly in the markdown, immediately before the text they refer to, so both humans and agents can work from the same file.

Some text <!-- @comment{
  "id":"uuid",
  "anchor":"highlighted text",
  "text":"Rewrite this section to be clearer.",
  "author":"User",
  "timestamp":"2026-03-26T12:00:00.000Z",
  "replies":[]
} -->highlighted text continues here.

This makes feedback:

visible to AI agents via a plain file read
portable with the markdown file
invisible in normal renderers (GitHub, VS Code preview)

Features

Review and commenting

Inline comments anchored to rendered text, including overlapping comments
Two-way agent review over MCP: agents request your review, review your docs, and ask anchored questions
Threaded replies and optional open / resolved review states
Adjustable anchors with drag handles
Touch and pen commenting: select with the native handles, then tap the floating Comment button when done (nothing pops up while you adjust)
Rendered, raw, and diff views
Hand-off prompt copying for one or multiple files

Multi-tab editing with session persistence and tab context menus
File explorer, recent files, and native OS file picker
Find in document (Cmd+F) with match navigation
Table of contents with scroll spy
Command palette (Cmd+K), keyboard shortcuts, and settings panel (Cmd+,)
Resizable panels and right-click context menus

Rendering and integrations

Real-time reload via SSE when files change externally
Mermaid diagram rendering with commentable text
YAML and TOML frontmatter rendered as commentable content, not hidden
Local image embeds and clickable links between markdown files
Customizable comment templates
8 themes: Light, Dark, Sepia, Nord, Solarized, GitHub, Rosé Pine, Catppuccin

Supported platforms

macOS: supported
Linux: supported; system file picker requires zenity
Windows: supported; system file picker uses PowerShell
Touch browsers (iPad Safari and similar): supported for reviewing and commenting; selections made by touch or pen use the floating Comment button flow

Permissions

By default, md-redline can read any markdown file in your home directory. The first time you run mdr (or the first time after upgrading from a version without the trusted-roots feature), your home folder is added to a trusted-roots list at ~/.md-redline.json. Files outside your home directory (/tmp, mounted volumes, system paths) require an explicit permission grant via the OS folder picker the first time you open them. Granted folders are remembered across restarts.

To use the strict per-folder model instead, run mdr --restrict once after install. This creates a ~/.md-redline.json with no default trust, and you'll grant each folder explicitly the first time you open a file in it.

File saves use atomic write-then-rename and mtime-based conflict detection to prevent data loss from concurrent edits. Mermaid SVG output is sanitized via DOMPurify before rendering. Only run md-redline in environments you trust.

Configuration

All of these environment variables are optional.

Variable	Default	Purpose
`MD_REDLINE_BROWSER`	OS default browser	Command used to open the review URL. Set it to a specific browser binary (for example `MD_REDLINE_BROWSER=firefox`); it is spawned with the URL as its argument. The older `MDR_BROWSER` still works: it is used whenever this one is unset or blank.
`MD_REDLINE_PORT` (or `PORT`)	`6373`	Port for the API server. It scans up to 10 ports upward from here if that one is taken. `MD_REDLINE_PORT` wins when both are set; a blank one defers to `PORT`.
`MD_REDLINE_VITE_PORT`	`5188`	Port for the Vite dev client (development only).
`MD_REDLINE_HOME`	your OS home directory	Base directory for md-redline's preferences file (`.md-redline.json`, which stores trusted roots and the update-check cache).
`MD_REDLINE_REGISTRY_URL`	public npm registry	Registry base URL used for the background update check.
`MD_REDLINE_ALLOWED_HOSTS`	unset	Comma-separated extra hostnames accepted by the Host-header check, so the loopback-bound server can sit behind a trusted reverse proxy. Read Reaching md-redline from another device before setting it.
`NO_UPDATE_NOTIFIER` or `CI`	unset	If either is present (any value, including empty), the background update check is disabled.

Reaching md-redline from another device

md-redline binds to 127.0.0.1 and has no authentication of any kind. That is safe today because only your own machine can reach it.

MD_REDLINE_ALLOWED_HOSTS lets you put a reverse proxy in front of it (tailscale serve, nginx, Caddy) and review from a tablet. It does not change the bind address, so the proxy still runs on the same machine. It does change the security boundary, from "my machine" to "anything that can reach the proxy".

Whatever reaches the proxy can read and write every markdown file under your trusted roots, browse those directories, see their absolute paths and your recent files, open native file pickers and reveal files in Finder on your machine, answer agent review sessions, and shut the server down. There is no login.

So if you set it:

Prefer tailscale serve, reachable only from your own tailnet. Do not use tailscale funnel, which publishes to the open internet.
With nginx or Caddy, terminate TLS and put authentication in front of md-redline yourself. It will not do it for you.
Only list hostnames you actually control. The DNS-rebinding defense still holds for everything else, because an attacker's rebinding domain never matches a hostname you listed explicitly.
Serve it over HTTPS if you can. The clipboard API the hand-off prompt copy needs only works in a secure context, so over plain HTTP that button fails on the very tablet you set this up for.

A reachable client cannot widen its own filesystem access: trusted roots grow only when you pick a file or folder in the native dialog, so the readable set stays whatever you approved locally.

Whether you need the variable at all depends on your proxy. tailscale serve and Caddy preserve the original Host, so you must list the public hostname. nginx's default proxy_set_header Host $proxy_host rewrites it to 127.0.0.1:6373, which already passes, so you only need the variable if you forward the original host (proxy_set_header Host $host).

Turn off response buffering for /api/watch. Live file updates arrive over Server-Sent Events. md-redline sends X-Accel-Buffering: no, which nginx honours; if your proxy ignores it, disable buffering for that path or edits will not appear until a buffer fills.

Why a hostile page cannot drive these endpoints. Every endpoint that changes something is a POST or a PUT requiring a JSON content type, which a web page cannot send to another origin without the browser asking this server for permission first. That is what stops a page you visit, a link in a chat message, or an image embedded in a markdown file you are reviewing from quietly triggering an endpoint here. md-redline additionally rejects requests a browser labels cross-site, but only as a second layer: clients that send no such metadata, like the CLI and the MCP server, are deliberately unaffected.

The full surface, if you want to audit it: GET/PUT /api/file, GET /api/browse, GET /api/files, GET /api/asset, GET/PUT /api/preferences, GET /api/config, GET /api/version, GET /api/platform, POST /api/pick-file, POST /api/pick-folder, POST /api/reveal, GET /api/watch, POST /api/shutdown, and /api/review-sessions/*. POST /api/grant-access only re-checks a path against roots you already approved rather than adding new ones.

Troubleshooting

The agent says it has no mdr tools. Restart your MCP client after mdr mcp install; most clients only discover new servers at launch. For non-Claude clients, confirm mdr is on the PATH the client actually uses (see MCP setup above).
The browser opened but the page will not load. A stale server may be holding the port. Run mdr --stop, then reopen your file.
A review banner is stuck on screen. Click End review (agent reviews) or Cancel review (your reviews). Sessions do not survive a server restart, but comments do.
Something went wrong mid-session. The file is always the source of truth. Comments and agent questions live in the markdown itself as  markers, so you can read, edit, or delete them in any editor, and the agent is always told to re-read the file when a session ends unexpectedly.

Development

From source

git clone https://github.com/dejuknow/md-redline.git
cd md-redline
npm install
npm run dev

Open the local URL printed by Vite (usually http://localhost:5188).

Scripts

npm run dev          # Start dev server
npm run lint         # Lint
npm test             # Production build + unit tests
npm run test:e2e     # Playwright E2E tests
npm run build        # Production build

Agent eval

The eval harness tests whether AI agents correctly read, address, and remove inline comments.

npm run eval:dry validates eval fixtures
npm run eval runs the full eval harness
See eval/README.md for details

Architecture

bin/md-redline             CLI entry point (invoked as `mdr` or `md-redline`)
bin/cli.js                 CLI implementation behind that entry point
server/index.ts            Hono server for file I/O, browsing, SSE, and local integrations
src/App.tsx                Main application shell
src/components/            Viewer, sidebar, raw view, diff view, TOC, explorer, settings, etc.
src/hooks/                 State, persistence, selection, file watching, drag handles, tabs
src/lib/comment-parser.ts  Inline comment parsing and mutation helpers
src/markdown/pipeline.ts   Markdown rendering pipeline
eval/                      Eval harness for agent behavior against inline comments
e2e/                       Playwright end-to-end coverage

License

MIT

Available Tools

4 tools

mdr_askA

Ask the user one or more questions anchored to specific text in a file inside an active review session. Each question becomes an inline marker the user sees and can reply to in the md-redline UI. Returns with the reply text as soon as the user has answered every question, or with whatever partial replies exist when they finish the review (Done / Finish review), or empty-handed if the session ends another way. Replies also land in the marker threads on disk, so when this tool returns without reply text you should re-read the file(s) before concluding the user did not answer. Use this when a comment is unclear, or when you hit a planning fork while editing. Prefer asking over guessing when the right answer would meaningfully change your edit.

Only one mdr_ask can be pending per session at a time. If this returns "a previous mdr_ask is still pending", post a reply to the prior question via mdr_comment — pass this same sessionId plus a replies: payload targeting that commentId, which resolves the pending ask in-place without opening a second session — and then retry mdr_ask with your new questions.

ParametersJSON Schema

Name	Required	Description	Default
`questions`	Yes
`sessionId`	Yes	Session ID from a previous mdr_comment call, or the sessionId of an active mdr_request_review handoff. Both work: asking a clarifying question about a comment the user left during their own review is the primary use case.

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations provided, the description carries the full disclosure burden and delivers: three distinct return modes (all answered, partial replies on Done/Finish review, empty-handed on other session ends), a side-effect warning that replies land in marker threads on disk with the instruction to re-read files before concluding the user didn't answer, and the one-pending-ask-per-session concurrency constraint with its recovery path.

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?

Every sentence earns its place: purpose, return semantics, disk side-effect warning, usage criteria, then concurrency/error recovery. The opening sentence front-loads the primary purpose, and the longer second paragraph is justified by the subtle pending-ask recovery flow it documents.

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?

For an async, user-interactive tool with no annotations and no output schema, the description covers purpose, all return cases, side effects, concurrency, and error recovery — remarkably complete. The main gap is that the reply payload shape is never specified ('returns with the reply text' / 'whatever partial replies exist' leaves the structure to inference), which an agent needs to know to consume the result reliably.

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?

Schema coverage is only 50%, so the description must compensate. It adds the anchoring concept behind filePath/anchor and the sessionId reuse-and-retry flow ('pass this same sessionId plus a replies: payload targeting that commentId'). However, contextAfter and contextBefore remain undocumented in both the schema and the description, leaving some parameter meaning to inference.

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 opens with a specific verb-resource pairing: 'Ask the user one or more questions anchored to specific text in a file inside an active review session.' It further explains the inline-marker mechanism, which clearly differentiates it from siblings like mdr_comment (posting replies) and mdr_request_review (starting a review handoff).

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?

Explicit usage criteria are given: 'Use this when a comment is unclear, or when you hit a planning fork while editing,' plus a decision heuristic: 'Prefer asking over guessing when the right answer would meaningfully change your edit.' It also covers the exclusion case — if a previous mdr_ask is pending, route through mdr_comment with a replies payload targeting that commentId instead of opening a second session.

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

mdr_commentA

Post YOUR OWN comments into markdown files for the user to read. Use this when the user asks YOU to review a doc and leave feedback on it.

If instead the user wants to review a doc THEMSELVES and have you address what they write ("I want to review X in mdr", "let me review X", "open X so I can comment"), call mdr_request_review, NOT this tool. The word "review" in those requests describes what the user is about to do, not what you should do. This tool writes your comments into their file, which is the opposite of what they asked for.

Returns IMMEDIATELY after posting (never blocks). In the filePaths form the returned sessionId MUST be passed to mdr_wait afterward to block until the user clicks Done — that is a two-tool flow: mdr_comment (post) → mdr_wait (block). This does NOT apply to the sessionId form below, which posts into a session you did not open; mdr_wait rejects user-origin sessions. Skipping mdr_wait leaves a banner on the user's screen until they click Done; you will not see their replies or edits before continuing, and any user feedback will be invisible to you for this turn.

The comments appear as inline markers anchored to specific text, which the user can then address.

Comments are anchored to exact text in the rendered document (not the raw markdown). For text inside Mermaid diagrams or markdown-formatted spans, the renderer will fall back to label/stripped matching.

Include author on each comment/reply identifying yourself (e.g. 'Claude', 'Codex', 'Gemini'). This appears in the mdr UI so the user knows which agent left the feedback.

To reply inside a review the user already has open — the session from an mdr_request_review handoff, or one this tool returned earlier — pass sessionId instead of filePaths. The batch lands in that session and no second tab or banner appears. Use it whenever you are replying as you work rather than posting a fresh review; the filePaths form always opens its own session.

ParametersJSON Schema

Name	Required	Description
`replies`	No
`comments`	No
`filePaths`	No	Absolute paths to markdown files to review. Opens a new session. Omit when passing sessionId.
`sessionId`	No	Post into this existing session instead of opening a new one. Accepts the sessionId of an active mdr_request_review handoff or of a previous mdr_comment call. Mutually exclusive with filePaths.
`enableResolve`	No

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and succeeds. It discloses non-blocking execution ('Returns IMMEDIATELY'), the required two-tool flow with mdr_wait, mdr_wait's rejection of user-origin sessions, banner and invisible-feedback consequences, the anchoring to rendered text with fallback behavior, and the author attribution requirement. This is rich behavioral context well beyond the basic 'post a comment' semantics.

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

Conciseness4/5

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

The description is long but front-loaded: purpose, trigger, and the key mdr_request_review distinction come first, then critical async/session behavior. Each paragraph carries necessary operational information that an agent must know to call this tool correctly, so the length is justified even though some sentences restate the same core contrast.

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?

Given the tool's complex two-session flow and the absence of an output schema, the description covers the major operational concerns: immediate return, mdr_wait sequencing, user-origin session restrictions, anchor/rendering behavior, and reply handling via sessionId. Minor gaps exist around enableResolve and the exact return value shape, but they are not likely to cause incorrect invocation.

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?

Schema coverage is only 40%, so the description's parameter guidance is valuable. It explains the central filePaths vs sessionId choice, states that filePaths opens a new session while sessionId posts into an existing one, and instructs the agent to include author on each comment/reply. However, it leaves enableResolve and the contextBefore/contextAfter fields unexplained, so it does not fully compensate for the schema gaps.

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 opens with a specific verb and resource: 'Post YOUR OWN comments into markdown files for the user to read.' It also explicitly differentiates the tool from mdr_request_review by explaining when 'review' refers to the user's action rather than the agent's, giving clear sibling distinction.

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?

Usage criteria are explicit: use when the user asks YOU to review a doc and leave feedback; do not use when the user wants to review themselves. It names the alternative tool (mdr_request_review), gives concrete example phrasings to detect the wrong case, and further distinguishes between the filePaths and sessionId flows with the mdr_wait dependency.

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

mdr_request_reviewA

Open markdown files in mdr (md-redline) so the USER can review them and leave comments for you to address, or continue an existing review session. Use this whenever the user wants to read, review, or comment on a doc themselves, including phrasings like "I want to review X in mdr", "open X so I can comment", or "let me look at X". The user is the reviewer here; you wait and then address what they write. To start a new review, pass filePaths. To continue after addressing a batch of comments, or to re-poll while the user is still reviewing, pass the sessionId from the previous result (without filePaths). If the result says the user has not finished yet, call again with the same sessionId to keep waiting. IMPORTANT: while this tool is waiting (no "batch" or "done" result has arrived yet, or you are between batches), you do not have permission to read, open, edit, or otherwise act on the files under review using other tools. The user is actively writing @comment markers into those files; reading them yourself will surface unsubmitted markers you must not address. Once a "batch" or "done" result arrives you may read/edit the files, but only to address the comments listed in that result — ignore any other @comment markers you encounter in the file.

ParametersJSON Schema

Name	Required	Description
`filePaths`	No	Absolute paths to markdown files to review (for new sessions).
`sessionId`	No	Session ID from a previous batch result. Pass this (without filePaths) to wait for the next batch of comments after addressing the previous batch.
`enableResolve`	No	Whether to use the resolve workflow (open/resolved states).

TDQS

A4.8/5.0

Behavior5/5

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

With zero annotations, the description carries the full behavioral burden and excels: it discloses the blocking/polling behavior (call again with the same sessionId), the permission restriction on other tools, the rationale (unsubmitted @comment markers), and the post-condition (only address listed comments, ignore other markers). This is precisely the operational context annotations would normally provide.

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

Conciseness4/5

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

Well-sequenced: purpose, trigger phrasings, session mechanics, critical restriction, then post-condition. Every sentence is informative, but it is a dense wall of text and the 'ignore unsubmitted markers' point is reinforced multiple times; minor tightening would not hurt.

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?

Despite having no output schema, the description defines the result vocabulary ('batch', 'done', 'not finished') and instructs on each outcome. For an interactive polling tool with a subtle safety restriction, everything required to call it correctly — init, continuation, waiting behavior, and post-batch handling — is present.

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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the relationship between filePaths and sessionId ('pass the sessionId from the previous result (without filePaths)') and the polling semantics — information that no per-property schema description conveys.

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?

States a specific verb + resource ('Open markdown files in mdr (md-redline)') and the intent: the USER reviews and leaves comments while the agent waits. It distinguishes itself from siblings by framing 'The user is the reviewer here; you wait and then address what they write,' making clear this is not the tool for the agent to comment or ask on its own.

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 gives the selection condition ('Use this whenever the user wants to read, review, or comment on a doc themselves') reinforced with concrete trigger phrasings. It also provides scenario mechanics (filePaths for new sessions, sessionId for continuation and re-polling) and an exclusion in the IMPORTANT block: other tools must not act on files under review while waiting.

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

mdr_waitA

Block until the user has finished engaging with an mdr_comment session. Call this once after you have posted all your feedback batches via mdr_comment. Returns when the user clicks Done in the mdr UI. If the wait times out (90s), returns {status:"pending"} — call mdr_wait again with the same sessionId to keep waiting. After this returns {status:"done"}, read the file(s) to see the user's replies, deletions, and resolutions.

ParametersJSON Schema

Name	Required	Description	Default
`sessionId`	Yes	Session ID returned by mdr_comment.

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full disclosure burden and does so thoroughly: it states that the call blocks, that the timeout is 90 seconds, that a timeout returns {status:'pending'}, that it may be retried, and that a done status should be followed by reading files for user edits. No contradictions with schema or 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?

Three sentences each carry essential information: purpose, timeout/retry behavior, and post-done follow-up. The most important verb is front-loaded and there is no filler or repetition of schema fields.

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 one-parameter tool with no output schema, the description covers the blocking behavior, both possible return statuses, the retry loop, and the subsequent action of reading files. Nothing an agent needs to invoke and handle this tool correctly is missing.

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 description coverage is 100% and already explains sessionId as 'Session ID returned by mdr_comment.' The tool description reinforces using the same sessionId on retry, a small behavioral addition, but not enough to raise the score above the baseline for fully documented parameters.

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 opens with a specific verb-resource pair: 'Block until the user has finished engaging with an mdr_comment session.' It clearly distinguishes itself from mdr_comment and sibling tools by positioning mdr_wait as the follow-up wait step after feedback batches are posted.

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?

It gives explicit sequencing: 'Call this once after you have posted all your feedback batches via mdr_comment.' It also specifies the retry pattern on timeout ('call mdr_wait again with the same sessionId') and what to do after done, leaving no ambiguity about when to invoke it.

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. Dates show when Glama detected each change.

4 tool updatesv0.9.0Aug 29, 2026

Changedmdr_ask1 field changed

changedInput schema / properties / sessionId / description

Previous value: -"Session ID from a previous mdr_review call, or the sessionId of an active mdr_request_review handoff. Both work: asking a clarifying question about a comment the user left during their own review is the primary use case."New value: +"Session ID from a previous mdr_comment call, or the sessionId of an active mdr_request_review handoff. Both work: asking a clarifying question about a comment the user left during their own review is the primary use case."

Addedmdr_comment
Removedmdr_review

Changedmdr_wait1 field changed

changedInput schema / properties / sessionId / description

Previous value: -"Session ID returned by mdr_review."New value: +"Session ID returned by mdr_comment."

3 tool updatesv0.7.2Jul 30, 2026
- Addedmdr_ask
- Addedmdr_review
- Addedmdr_wait
3 tool updatesv0.7.1Jul 19, 2026
- Removedmdr_ask
- Removedmdr_review
- Removedmdr_wait
3 tool updatesv0.5.0Jun 29, 2026
- Addedmdr_ask
- Addedmdr_review
- Addedmdr_wait
1 tool updatev0.3.2Apr 28, 2026
- First observedmdr_request_review

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.8/5.0

Disambiguation4/5

Each tool has a distinct role: user-initiated review, agent-posted comments, anchored questions, and blocking on completion. The main overlap risk between mdr_request_review and mdr_comment is explicitly addressed in the descriptions, though the shared 'review' vocabulary still demands careful reading.

Naming Consistency5/5

All tools use the mdr_ prefix followed by a clear verb: request_review, comment, ask, wait. The naming pattern is uniform and predictable.

Tool Count5/5

Four tools is well-scoped for a focused markdown review workflow. Each tool covers a distinct phase of the review lifecycle without redundancy or bloat.

Completeness5/5

The set covers both directions of review: user reviewing with agent addressing, agent commenting for the user, inline questions, and blocking until the user finishes. The workflow feels complete for the stated purpose.

Maintenance

ActivityActive

ResponsivenessWithin a week

Resources

Need Help?

Related Servers

Related MCP Connectors

MarkupBase AOAuth
com.markupbase.mcp
MarkupBase turns AI-generated Markdown and HTML into durable, versioned artifacts that people can review and discuss. Its MCP server lets agents publish new versions, preserve contextual comments, include hosted images, and respond to feedback through secure account-linked identities, creating a clear human review boundary without requiring real-time editing.
Content Management Systems RAG Systems Workplace & Productivity
122
meok-agents-md-lint-mcp
io.github.CSOAI-ORG
MEOK AGENTS.md Linter MCP — validates the cross-vendor coding-agent spec (Cursor / Claude Code /
Code Analysis Developer Tools
1
MarkupBase AOAuthDeprecated
com.markupbase
Versioned artifact review for people and AI agents, with contextual comments and human control.
Developer Tools Project Management Workplace & Productivity
121
Commentary ReviewOAuth
dev.commentary
Human-owned review for agent plans, rendered documents, Forms, research, and live previews.
Autonomous Agents Product Management Testing & QA Tools
1

Related MCP Servers

md-feedback
Developer Tools Autonomous Agents Agent Orchestration
yeominux
F
license
Not graded
quality
B
maintenance
An MCP server for reviewing markdown plans before AI agents implement them. Enables annotation of plans with Fix, Question, and Highlight, which AI agents can read directly through MCP.
Updated 5 months ago (2026-03-23 13:16 UTC)
5
-
md-annotate
Developer Tools Content Management Systems
alaeddineG
A
license
Not graded
quality
D
maintenance
A local-first markdown review tool with MCP integration, enabling AI and humans to collaboratively annotate documents inline and generate revision prompts.
Updated 5 months ago (2026-03-30 12:52 UTC)
1
MIT
pad-core
Note Taking Communication
zyx1121
A
license
Not graded
quality
F
maintenance
MCP server for collaborative markdown editing, allowing agents to write documents and humans to comment, with comments fed back as agent input.
Updated 2 months ago (2026-07-21 12:05 UTC)
324,912
MIT
reader3000-mcp
Workplace & Productivity Note Taking
angelux
A
license
Not graded
quality
C
maintenance
Enables sharing Markdown documents for collaborative review with inline annotations and structured change requests.
Updated 2 months ago (2026-07-06 07:17 UTC)
14
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dejuknow/md-redline'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

md-redline

Quick start

Updating

MCP setup

Claude Code or Claude Desktop

Codex CLI

Gemini CLI

Other MCP clients

Review workflow

1. You review the agent's doc

2. The agent reviews your doc

Either direction: the agent can ask you questions

Without MCP

Optional: resolve workflow

Who this is for

Non-goals

How comments are stored

Features

Review and commenting

Navigation and editing

Rendering and integrations

Supported platforms

Permissions

Configuration

Reaching md-redline from another device

Troubleshooting

Development

From source

Scripts

Agent eval

Architecture

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API