mdreview

mdreview-service

コンテナ化された Markdown レビュー用マイクロサービスです。エージェントが Markdown を POST すると、人間が確認するためのレビュー URL が返され、HTTP 経由でフィードバックをポーリングできます。1 つのサービスで複数のレビューを処理し、それぞれを ID で分離します。 プロセスごとの起動は不要で、エージェントとのファイルシステム共有もありません。

ランディングページ： mdreview.space（GitHub Pages から配信。設定は .github/workflows/pages.yml、ソースは web/site/ にあります）。

ドキュメント： mdreview.space/docs：導入ガイド、操作方法、トラブルシューティングを、サービス独自の Markdown レンダラーで表示します（ソースは web/site/docs/ にあります）。

はじめに：ホスト版またはセルフホスト

mdreview の使用方法は 2 つあります。どちらかを選んでください。

1. ホスト版（オンライン）。 マネージドインスタンスを mdreview.space（アプリは app.mdreview.space）で利用できます。任意のメールアドレスでサインインしてください（ワンタイムリンクが届きます。招待リストはありません）。エージェントを接続する方法は 3 つあります。

claude.ai カスタムコネクター（トークン不要）。 claude.ai で 設定、コネクター、カスタムコネクターを追加 を開き、次を入力します。

https://app.mdreview.space/mcp

Claude から mdreview のサインイン画面が開きます。メールアドレスを入力し、ワンタイムリンクからアクセスして、同意ページで接続を承認してください。ウェブ版、デスクトップ、モバイルの claude.ai で利用できます。アカウントページからいつでも接続を取り消せます。

Claude Code プラグイン。 Claude Code 内で次を実行します。

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

トークンの入力を求められます（サインイン後、アカウントページで発行できます）。トークンはキーチェーンに保存されます。プラグインの更新は /plugin update で適用されます。ラッパー自体はプラグイン内で更新されません。

インストーラー。 エージェントを実行するマシンで（claude CLI と python3 が必要です）、アカウントページから取得したトークンを使って次を実行します。

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

これにより、標準ライブラリのみを使用する MCP ラッパーが ~/.mdreview に取得され、ユーザースコープで Claude Code に登録されます。Claude Code を終了して再度開くと接続されます。トークンの入力を求める場合は MDREVIEW_TOKEN=… を省略してください。（手動で接続する場合や、Claude Code 以外の MCP クライアントを使う場合は、MCP サーバー を参照してください。）

2. セルフホスト版（ローカル）。 自分でクローンして実行します（アカウント不要、認証なし、localhost で動作）。実行 を参照し、エージェントの MCP MDREVIEW_BASE を http://localhost:8137 に設定してください。すべてを自分のマシン上で完結させたい場合はこちらを選びます。

Python の標準ライブラリのみを使用します（イメージは小さく、pip によるインストールは不要です）。単体で動作します。marked、Mermaid、KaTeX、highlight.js、脚注のレンダラーは同梱され、/static から配信されるため、ブラウザーから CDN へアクセスする必要はありません。ビューアーは Jekyll/MathJax サイトと同じように Markdown をレンダリングします。LaTeX 数式（インラインの $…$ / \(…\)、ディスプレイ形式の $$…$$ / \[…\]。文章や通貨の $ はそのまま表示）、Mermaid 図、GFM 脚注（[^id] の参照から、元の位置へのリンクを含む順序付きセクションを生成）、シンタックスハイライト付きのフェンスコード（ライト・ダーク両方のペインで読みやすいデュアルスキームのテーマ）に対応しています。

実行

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）がローカル Docker での標準的な起動方法です。8137 番ポートで配信され、名前付きの mdreview-data ボリュームを再利用するため、再ビルドや再作成をしてもレビューは保持されます。

ヘルスチェック：curl localhost:8137/healthz -> {"ok":true}。

フィードバックとソースは、再起動後も /data ボリュームに保持されます。

従来の手動起動コンテナからの移行

以前のインスタンスを手動で起動していて（標準外のポート、たとえば :8139 で docker run を実行）、データを失わずに標準の compose フローへ移行する場合、mdreview-data ボリュームはそのまま再利用されます。

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

compose ボリュームは、プロジェクト名が付いた infra_mdreview-data ではなく、明示的な name: mdreview-data で宣言されるようになったため、make up は以前のコンテナが使用していたボリュームをそのままマウントします。curl localhost:8137/healthz で確認し、レビューが引き続き一覧に表示されることを確認してください。

フロー

1. エージェント：POST /api/reviews {markdown, title} -> {id, review_url, feedback_url, ...}
2. エージェントが review_url を人間に渡します。
3. 人間が開き、テキストを選択するか段落番号をクリックして、メモを入力します（自動保存されます）。
4. エージェントが GET /api/reviews/{id}/status をポーリングし、続けて GET /api/reviews/{id}/feedback を取得します。
5. エージェントが編集を適用して PUT /api/reviews/{id}/source {markdown} を実行すると、人間のページが ライブリロードされ、対応済みのメモに取り消し線が引かれます。必要に応じて繰り返します。

設定（環境変数）

変数	デフォルト	意味
PORT	8080	コンテナ内のリッスンポート
MDREVIEW_DATA	/data	ストレージディレクトリ（ボリュームをマウントします）
MDREVIEW_PUBLIC_BASE	空	設定されている場合（例：https://review.example.com）、review_url／feedback_url でこの値を使用します。未設定の場合は、リクエストの Host ヘッダーを使用します
MDREVIEW_ENABLE_LATEX	オフ	オプトイン：LaTeX 論文レビュー機能を有効にします（下記参照）。mdreview-service-latex イメージ（Tectonic）が必要です。デフォルトのスリムイメージには LaTeX ツールチェーンが含まれていません

運用ガイド

このページを読みやすく保つため、以前ここにあった運用手順書を別の場所に移しました。

ガイド	内容
HTTP API	すべてのルート、リクエストとレスポンスの形式
MCP サーバー	stdio サーバーの実行、スモークテスト
LaTeX 論文レビュー	有効化、テンプレート、コンパイルループ、イメージの運用手順
ウォッチャー	エージェントウォッチャー、信頼済みベースモード、コンテナ化された実行
デザインシステム	§01-§10、チケットで参照する UI ルール
自律実行	エージェントがこのプロジェクトの変更をリリースする方法

注記

• ID によるマルチテナント方式のため、レビューが同時に行われても競合しません。認証はありません（信頼できるネットワーク／ローカルネットワークでの利用を想定）。外部に公開する場合は、認証付きのリバースプロキシの背後に配置してください。
• ダッシュボード（/）と GET /api/reviews の一覧には、すべてのレビューが表示されます。信頼できるネットワークでの利用には問題ありませんが、外部に公開する場合は認証を前段に置く理由になります。
• 上記の MCP ラッパーは docs/future-mcp.md で設計され、この設計／意思決定記録として保持されています。
• エージェントとの連携の詳細については、CLAUDE.md を参照してください。
• Docker を使わないファイル単位の CLI 版は ../mdreview にあります（フィードバックをソースの隣にあるファイルに書き込みます）。このサービスは、ネットワーク対応のマルチセッション版です。

ライセンス

Apache License 2.0。

プライバシーポリシー

app.mdreview.space のホステッドサービスでは、アカウントのメールアドレス、レビューとコメント、サインインに関するセキュリティ記録を保存します。分析やトラッキング用 Cookie は使用せず、データを販売したり、AI モデルのトレーニングに使用したりすることもありません。保持、削除、サードパーティサービスを含むポリシー全文は、https://mdreview.space/privacy/ をご覧ください。お問い合わせは [email protected] までお寄せください。セルフホストのインスタンスでは、すべてのデータがご利用のマシンに保存されます。