Markdown Review

Markdown Review は、ドキュメントの編集可能なコピーを別途作成せずに、レンダリング済み Markdown をレビューするためのローカルファーストの MCP Apps インターフェースです。文章を選択するか画像を選び、行に紐づくフィードバックをキューに入れ、レビュー全体を一度にコーディングエージェントへ送信します。Codex App が最初にリリースされた対話型ホストです。コアの契約、状態、UI は意図的にホスト非依存として設計されており、将来の Claude、pi、ターミナル、Tauri アダプタに対応できます。

ステータス: 初期開発段階。Codex App がリリース済みの対話型ホストです。再利用可能な UI と MCP トランスポートは MCP Apps 標準に従うため、レビューコアを書き直すことなく追加のホストアダプタを追加できます。

提供される機能

• サイドパネルでの全画面の GitHub スタイル Markdown プレビュー。

• 通常のテキスト選択とコピーに加え、選択テキスト、画像、ドキュメント全体に対するフィードバック用のレビューメニュー。

• ポインタ、タッチ、キーボードでのコメントに対応したフォーカス可能な画像レビューターダット。

• 画像の右下に、ホバー時、キーボードフォーカス時、またはアクティブなタッチ時のみ表示される控えめな画像フィードバックコントロール。

• #1、#2 のように番号付けされたインラインコメントマーカー。

• すべてのコメントをまとめて送信し、競合する編集を避けるレビューキュー。

• #N を使用したキュー内コメント間の参照。リテラルテキストには \#N または `#N` を使用します。

• 相対ローカル PNG、JPEG、静的 WebP のレンダリングと、境界付きのプライベートチャンク転送。

• Codex が Markdown ドキュメントを作成または実質的に編集した後の自動レビュー。

Markdown ソースは常に正規のものです。コンポーネントは読み取り専用のレビューサーフェスであり、ソースファイルを編集するのは Codex のみで、通常のファイルシステムツールを使用します。

Related MCP server: md-annotate

仕組み

local .md file
    │
    ├── open_markdown_review ──► sanitized rendered component (private UI payload)
    │                                  │
    │                                  └── queued, line-anchored comments
    │                                                   │
    └◄──────────── Codex edits the original file ◄──────┘
                              one batch message

MCP サーバーは意図的に狭い範囲に限定されています:

1. open_markdown_review は絶対パスの .md または .markdown を検証してレンダリングします。

2. コンポーネント専用ツールは、レンダリングされたドキュメントをハイドレートし、承認されたローカルラスター画像を境界付きチャンクでストリーミングします。

3. モデルから見えるツール結果にはファイルメタデータが含まれ、完全なドキュメントは含まれません。レンダリングされたコンテンツはコンポーネントにプライベートに配信されます。

4. スキルは、Codex がレビューフィードバックを解釈し、基になる Markdown を安全に変更する方法を説明します。

この分離が、このプロジェクトに MCP が含まれる理由です。サーバーは Codex のツール呼び出しを信頼できる対話型コンポーネントに接続します。静的 HTML ファイルだけでは、選択されたソースファイルを受け取ったり、構造化されたレビューコメントをアクティブなタスクに返したり、このコンテキスト境界を維持したりすることはできません。

実装はホスト非依存の TypeScript ワークスペースに分割されています。contracts はすべての境界を検証し、core は純粋なレビュー状態を所有し、markdown-node はローカルファイルを読み取ってレンダリングし、review-ui は狭いドキュメント、送信、プレゼンテーション、状態ポートにマウントされます。host-mcp-apps は標準ベースのランタイムを提供し、そのデフォルトの送信は構造化 JSON です。Codex ブラウザ構成は、簡潔な $markdown-review フォーマッタを明示的に追加します。レビュー状態は不透明なレビューセッション ID の下でローカルに永続化されるため、キューに入れられたコメントはコンポーネントの再マウント後も存続しますが、モデルから見えるレガシーウィジェットコンテキストとして公開されることはありません。将来の Tauri シェルは、契約、コア、UI を再利用し、Rust IPC ポートを提供できます。Tauri は現在含まれていません。

ホストサポート

未リリースのアダプタとブラウザ受け入れのフォローアップは ROADMAP.md で追跡されています。

リポジトリマーケットプレイスからインストール

要件:

• プラグインサポート付きの ChatGPT デスクトップアプリ内の Codex。

• node として利用可能な Node.js 22 以降。

• マーケットプレイスソースを追加するための codex CLI。

このリポジトリをマーケットプレイスとして追加します:

codex plugin marketplace add tjs-w/markdown-review --ref main

デスクトップアプリを再起動し、プラグインディレクトリを開いて、Markdown Review を選択し、プラグインをインストールします。インストール後、新しいタスクを開始して、タスクがプラグインツール登録を受け取るようにします。

既存のインストールを更新するには:

codex plugin marketplace upgrade markdown-review

デスクトップアプリを再起動し、アップグレード後に新しいタスクを開始します。既存のタスクは、開始時に持っていたツールとスキル登録を保持します。

使用方法

Codex に絶対 Markdown パスを開くように依頼します:

Open /absolute/path/to/document.md for Markdown review.

レビュー内で:

1. テキストを選択し、必要に応じて通常どおりコピーするか、レンダリングされた画像を選択します。

2. ドキュメントを右クリックするか、Review を選択してコピーとコメントのアクションを実行します。選択範囲の + アクションと各画像ターゲットは、直接のショートカットのままです。

3. Enter キーを押してコメントをキューに入れます。新しい行には Shift+Enter を使用します。

4. #1、#2 などを使用して、以前にキューに入れたコメントを参照します。

5. レビューラウンドが完了したら、Submit を選択します。

送信が成功すると、キューはクリアされ、次のレビューラウンドが再び #1 から始まります。個別送信アクションは意図的にありません。バッチ処理により、Codex は一貫した改訂ターゲットを 1 つ受け取り、ソースの競合を減らします。

ローカル開発

git clone https://github.com/tjs-w/markdown-review.git
cd markdown-review
bun install --frozen-lockfile
bun run verify

開発と CI は、固定された Bun 1.4 ツールチェーンを使用します。インストールされたプラグインに Bun は必要ありません。リポジトリには、読み取り可能な Node 互換の server.cjs と、minify されたブラウザバンドルがチェックインされています。TypeScript ソースを変更した後に再ビルドします:

bun run build

UI 作業用に Markdown ファイルに対してブラウザハーネスを実行します:

bun run browser:harness -- /absolute/path/to/document.md

ハーネスでフィードバックコンポーザを自動的に開くには、MARKDOWN_REVIEW_PREVIEW_COMPOSER=1 を設定します。

プラグインは、デフォルトでホストのネイティブコンテキストメニューを抑制します。ローカルプラグインデバッグ専用に、MCP サーバー環境で MARKDOWN_REVIEW_DEVTOOLS=1 を設定し、Codex を再起動します。Shift+右クリック でレビューメニューをバイパスし、ホストネイティブメニューが開きます。通常の右クリックでは引き続きレビューアクションが表示されます。フラグは厳密に解析されます。正確な値 1 のみがバイパスを有効にし、チェックインされた .mcp.json では決して有効になりません。

このチェックアウトをローカルマーケットプレイスとしてテストするには、その絶対ディレクトリを追加します:

codex plugin marketplace add /absolute/path/to/markdown-review

次に、デスクトップアプリを再起動し、ローカルマーケットプレイスソースからプラグインをインストールします。

安全性とプライバシーの境界

• コンポーネントは Markdown ファイルを書き込むことはできません。

• ローカル MCP サーバーが明示的な開発者フラグで起動されない限り、プラグイン内ではネイティブブラウザコンテキストメニューが抑制されます。これは UI の強化であり、Codex App 自体のメニューやショートカットに対するセキュリティ境界ではありません。

• レンダリングされた HTML は、コンポーネントに到達する前にサニタイズされます。

• リモート、絶対パス、ディレクトリ外の画像は読み込まれません。

• Markdown ファイルのディレクトリ内にある PNG、JPEG (.jpg/.jpeg)、静的 WebP ファイルへの相対パスのみがサポートされます。サーバーは、ブラウザがネイティブデコードを実行する前に、拡張子、シグネチャ、境界付きコンテナ構造、寸法、アニメーションポリシーを検証します。GIF、AVIF、SVG、APNG、アニメーション WebP はレンダリングされません。

• コンポーネントリソースは、ネットワークまたはリモートリソースドメインを宣言せず、明示的な 選択したテキストをコピー アクションのためのクリップボード書き込みアクセスのみを要求します。

• Markdown ファイルは 2 MiB に制限されています。

• レビューでは、無効な参照を含め、最大 64 個のローカル画像参照、一意の画像あたり 5 MiB、一意の画像スナップショットの合計 12 MiB を処理し、画像ごとのデコード寸法の厳格な制限があります。有効な参照はすべてレンダリングされます。ブラウザは、ドキュメント全体で境界付きの 24 メガピクセルのキャンバス予算を公平に共有し、大きな画像は省略せずに表示用にダウンスケールします。同じ正規ファイルまたは同一ダイジェストに解決される参照は、1 つの不変スナップショットと検証済みのクライアントデコードを共有します。

• 正規パスと開かれたファイルの ID は、各境界付き読み取りの前後に再チェックされます。これらのチェックは、読み取り中にドキュメントディレクトリ階層を継続的に置き換えることができる別のローカルプロセスに対する OS サンドボックスではなく、多層防御です。

• コンポーネントアクセスは、不透明で期限切れになるレビューセッション機能を使用します。セッションは 2 時間スライドし、6 セッションの LRU と 72 MiB の集約画像キャッシュによって制限されます。

• 画像バイトと SHA-256 ダイジェストはセッションにスナップショットされるため、後でファイルが変更されても進行中のレビューを変更できません。

• 完全なドキュメントコンテンツと画像チャンクは、モデルから見える構造化出力ではなく、コンポーネントプライベートメタデータに配置されます。

ローカルプラグインプロセスに公開するつもりのファイルのみをレビューしてください。送信されたコメントは実行可能なユーザーフィードバックです。選択された引用やその他のレビューされたドキュメントコンテンツは、信頼されていないコンテキストであり、指示ではありません。

プロジェクト構成

トラブルシューティング

プラグインファイルは存在するが、レビューツールが登録されていない。 デスクトップアプリを再起動し、新しいタスクを開始します。タスクは、そのタスクの開始後にインストールまたは更新されたプラグインからツールを動的に取得しません。

Codex がキャッシュされたスキルパスが移動したと言う。 マーケットプレイスプラグインをアップグレードまたは再インストールし、アプリを再起動して、新しいタスクで安定したスキル名 $markdown-review を呼び出します。バージョン付きキャッシュパスに依存しないでください。

サイドパネルが空白です。 プラグインチェックアウトで bun run verify を実行し、bun run build で再ビルドし、マーケットプレイスインストールを更新して、新しいタスクで再試行します。

ローカル画像がレンダリングされない。 Markdown ファイルのディレクトリ内にある相対 .png、.jpg、.jpeg、または静的 .webp パスを使用し、文書化されたサイズと寸法の制限内であることを確認します。

ドキュメント

• OpenAI: プラグインをパッケージ化する

• OpenAI プラグインドキュメント

これは独立したプロジェクトであり、OpenAI または GitHub の公式製品ではありません。製品名とマークは、それぞれの所有者に帰属します。