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, one command). A managed instance runs at mdreview.space (app at app.mdreview.space). Sign in with Google, open Connect your agent, and mint an API token. Then, on the machine running your agent (needs the claude CLI + python3):

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. Access is invite-only (an email allowlist), so this works only if the instance owner has added your Google email; otherwise ask for an invite, or self-host below. (To wire it up by hand, or for a non-Claude-Code MCP client, see MCP server.)

Or install it as a Claude Code plugin, with no installer. Inside Claude Code run /plugin marketplace add ranawaqas-ai/mdreview-service, then /plugin install mdreview@mdreview. It prompts for the token and keeps it in your keychain. Plugin updates arrive through /plugin update; the wrapper does not update itself inside a plugin.

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 for anyone: no invite needed.

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        # 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:

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)

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:

Guide	What it covers
HTTP API	Every route, request and response shape
MCP server	Running the stdio server, smoke tests
LaTeX paper review	Enabling it, templates, the compile loop, the image runbook
Watcher	The agent watcher, trusted-base mode, containerized runs
Design system	§01-§10, the UI rules that tickets cite
Autonomous runs	How 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.