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:
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:
/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:
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
make up
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:
docker rm -f mdreview
make up
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
- Agent:
POST /api/reviews {markdown, title} -> {id, review_url, feedback_url, ...}
- Agent hands
review_url to a human.
- Human opens it, selects text or clicks a paragraph number, types notes (auto-saved).
- Agent polls
GET /api/reviews/{id}/status then GET /api/reviews/{id}/feedback.
- 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)
| Var | Default | Meaning |
|---|
PORT | 8080 | in-container listen port |
MDREVIEW_DATA | /data | storage dir (mount a volume) |
MDREVIEW_PUBLIC_BASE | empty | if set (e.g. https://review.example.com), review_url/feedback_url use it; otherwise the request Host header is used |
MDREVIEW_ENABLE_LATEX | off | opt-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:
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 rana.waqas.works@gmail.com. A self-hosted instance keeps all data on your machine.