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).

Related MCP server: md-annotate

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)

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.