mdreview

io.github.ranawaqas-aiPublished by GitHub account ranawaqas-aiv0.7.0Updated Oct 28, 2026

Human-in-the-loop document review: an agent pushes a draft, a person comments, the agent revises.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowFiles & Storage

Overview

AI-generated overview

Lets an agent submit a Markdown draft for human review, collect a person's inline comments, and revise the document until the notes are addressed.

What you can do
  • Create a review from a Markdown draft and title, receiving a review link to hand to a person
  • Check review status and read the comments a reviewer left on selected text or paragraphs
  • Update the document source so the reviewer's page reloads live and addressed notes are struck through
  • List and manage multiple concurrent reviews, each isolated by its own id
When to use it
Useful when an agent writes Markdown documents, specs, docs or papers and a human needs to comment on them before the agent revises. It fits review loops where feedback should be captured in a browser page rather than pasted back into the chat.
Requirements
A remote endpoint at app.mdreview.space with OAuth sign-in by email one-time link, or a self-hosted Docker instance on localhost with no account. The hosted path can also use a token from the Account page for the Claude Code plugin or installer; the installer needs the claude CLI and python3. Self-hosting needs Docker and a data volume.
Before you install
The hosted service stores your account email, reviews and comments; a self-hosted instance keeps data on your machine. The self-hosted service has no authentication and its dashboard lists all reviews, so it should sit behind an authenticating reverse proxy if exposed. Agents write and overwrite review source, and review links are shared with other people.

Installation

In SourceWeft

  1. Open mdreview in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.ranawaqas-ai%2Fmdreview/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "mdreview": {
      "type": "http",
      "url": "https://app.mdreview.space/mcp"
    }
  }
}

README

mdreview-service

A containerized markdown review microservice. An agent POSTs markdown, gets back a review URL for a human, and polls feedback over HTTP. One service handles many reviews, isolated by id. No per-process spawning, no shared filesystem with the agent.

Landing page: mdreview.space (served from GitHub Pages via .github/workflows/pages.yml; source in web/site/).

Docs: mdreview.space/docs: onboarding, how-to, and troubleshooting, rendered through the service's own markdown renderer (source in web/site/docs/).

Getting started: hosted or self-hosted

Two ways to use mdreview; pick one.

1. Hosted (online). A managed instance runs at mdreview.space (app at app.mdreview.space). Sign in with any email address (you get a one-time link; there is no invite list). Three ways to connect your agent.

claude.ai custom connector (no token). In claude.ai open Settings, Connectors, Add custom connector and enter:

text
https://app.mdreview.space/mcp

Claude opens the mdreview sign-in; enter your email, follow the one-time link and approve the connection on the consent page. It works in claude.ai on the web, Desktop and mobile. Revoke it any time on the Account page.

Claude Code plugin. Inside Claude Code run:

text
/plugin marketplace add ranawaqas-ai/mdreview-service/plugin install mdreview@mdreview

It prompts for a token (mint one on the Account page after signing in) and keeps it in your keychain. Plugin updates arrive through /plugin update; the wrapper does not update itself inside a plugin.

Installer. On the machine running your agent (needs the claude CLI + python3), with a token from the Account page:

sh
curl -fsSL https://mdreview.space/install.sh | MDREVIEW_TOKEN=mdr_xxx sh

That fetches the stdlib-only MCP wrapper into ~/.mdreview and registers it with Claude Code at user scope; quit and reopen Claude Code and you are connected. Omit MDREVIEW_TOKEN=… to be prompted for it instead. (To wire it up by hand, or for a non-Claude-Code MCP client, see MCP server.)

2. Self-hosted (local). Clone and run it yourself (no account, no auth, on localhost). See Run, then point your agent's MCP MDREVIEW_BASE at http://localhost:8137. This is the path if you want everything on your own machine.

Stdlib Python only (tiny image, no pip installs). Self-contained: the marked, Mermaid, KaTeX, highlight.js, and footnote renderers are vendored and served from /static, so the browser needs no CDN. The viewer renders Markdown the way a Jekyll/MathJax site does: LaTeX math (inline $…$ / \(…\), display $$…$$ / \[…\]; prose/currency $ left literal), Mermaid diagrams, GFM footnotes ([^id] refs → an ordered back-ref section), and syntax-highlighted fenced code (a dual-scheme theme that reads on light and dark panes).

Run

bash
make up        # serves on http://localhost:8137# or:docker build -f infra/Dockerfile -t mdreview-service .docker run -d -p 8137:8080 -v mdreview-data:/data mdreview-service

make up (compose) is the canonical local-docker path; it serves on 8137 and reuses the named mdreview-data volume, so a rebuild/recreate preserves your reviews.

Health check: curl localhost:8137/healthz -> {"ok":true}.

Feedback and source persist in the /data volume across restarts.

Migrating a legacy hand-run container

If you have an older instance started by hand (docker run on a nonstandard port such as :8139), move it onto the canonical compose flow without losing data: the mdreview-data volume is reused as-is:

bash
docker rm -f mdreview     # stop the hand-run container (the mdreview-data volume survives)make up                   # compose recreates it on 8137, mounting the same mdreview-data volume

Because the compose volume is now declared with an explicit name: mdreview-data (not a project-prefixed infra_mdreview-data), make up mounts the very volume your old container owned. Confirm with curl localhost:8137/healthz and check your reviews are still listed.

The flow

  1. Agent: POST /api/reviews {markdown, title} -> {id, review_url, feedback_url, ...}
  2. Agent hands review_url to a human.
  3. Human opens it, selects text or clicks a paragraph number, types notes (auto-saved).
  4. Agent polls GET /api/reviews/{id}/status then GET /api/reviews/{id}/feedback.
  5. Agent applies edits and PUT /api/reviews/{id}/source {markdown} -> the human's page live-reloads and addressed notes are struck through. Repeat as needed.

Config (env)

VarDefaultMeaning
PORT8080in-container listen port
MDREVIEW_DATA/datastorage dir (mount a volume)
MDREVIEW_PUBLIC_BASEemptyif set (e.g. https://review.example.com), review_url/feedback_url use it; otherwise the request Host header is used
MDREVIEW_ENABLE_LATEXoffopt-in: enable the LaTeX paper review mode (see below). Requires the mdreview-service-latex image (Tectonic); the default slim image has no LaTeX toolchain

Operator guides

The runbooks that used to live here, moved out so this page stays readable:

GuideWhat it covers
HTTP APIEvery route, request and response shape
MCP serverRunning the stdio server, smoke tests
LaTeX paper reviewEnabling it, templates, the compile loop, the image runbook
WatcherThe agent watcher, trusted-base mode, containerized runs
Design system§01-§10, the UI rules that tickets cite
Autonomous runsHow agents ship changes here

Notes

  • Multi-tenant by id, so concurrent reviews never collide. No auth (intended for trusted / local networks); put it behind a reverse proxy with auth if exposing it.
  • The dashboard (/) and GET /api/reviews list across all reviews: fine for the trusted-network posture, but a reason to keep auth in front when exposed.
  • The MCP wrapper above was designed in docs/future-mcp.md, kept as its design/decision record.
  • For agent integration details, see CLAUDE.md.
  • A non-Docker, per-file CLI version lives in ../mdreview (writes feedback to a file next to the source). This service is the networked, multi-session form.

License

Apache License 2.0.

Privacy Policy

The hosted service at app.mdreview.space stores your account email, your reviews and comments, and sign-in security records. It uses no analytics or tracking cookies, does not sell your data and does not use it to train AI models. The full policy, including retention, deletion and third-party services, is at https://mdreview.space/privacy/. Questions go to [email protected]. A self-hosted instance keeps all data on your machine.

Source: README.md at commit 2a3df6f

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

2
  1. v0.7.0LatestSep 29, 2026
  2. v0.6.0Sep 25, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts