plsreadme

課題

README、PRD、会議メモ、APIドキュメントなどをマークダウンで作成した際、マークダウンレンダラーを持っていない人やGitHubを使わない人に共有する必要がある場合、ブラウザで開けるクリーンなリンクが必要です。

plsreadme は、あらゆるマークダウンをワンステップで永続的かつ美しくレンダリングされたWebページに変換します。アカウント作成やサインアップは不要。摩擦ゼロです。

✨ 機能

• インスタント共有 — マークダウンを貼り付けるかファイルをアップロードして、plsrd.me リンクを取得

• 美しいレンダリング — クリーンなタイポグラフィ、ダークモード、モバイル対応

• インラインコメント — 読者は任意の段落をクリックしてフィードバックを残せます

• レビューモード（現在 vs タイムライン） — 複数バージョンのドキュメントでは、デフォルトで現在のドラフトへのフィードバックを表示し、ワンクリックで完全なタイムライン履歴にアクセス可能

• AI自動フォーマット — 生テキストを投げれば、クリーンなマークダウンとして出力

• MCPサーバー — Claude、Cursor、VS Code、または任意のMCPクライアントから直接ドキュメントを共有

• OpenClawスキル — AIエージェントワークフロー向けに ClawHub で利用可能

• ショートリンク — すべてのドキュメントにコンパクトな plsrd.me/v/xxx URLを発行

• Rawアクセス — 共有リンクから元の .md ファイルをダウンロード可能

• バージョンタイムライン + 安全な復元 — /v/:id/versions + /v/:id/history + アーカイブ優先の復元APIによる迅速なロールバック

• Clerk認証基盤 — GitHub/Googleサインイン連携 + Clerkホスト型メールフォールバック + バックエンド認証検証ユーティリティ

• 所有権モデル（フェーズ2） — 匿名フローを維持しつつ、ドキュメントをClerkユーザー（owner_user_id）に紐付け可能

• マイリンクダッシュボード（フェーズ3） — 認証済みユーザー向けの /my-links ページ（検索・並び替え・ページネーション・クイックコピー/オープン機能付き）

• レガシーリンクの請求（フェーズ4） — サインイン済みユーザーが元の admin_token を証明することで、古い匿名リンクを自分のものとして請求可能

• ゼロコンフィグのウェブサイトデモ — ブラウザで試すのにアカウントやAPIキーは不要

🚀 クイックスタート

ウェブ

plsreadme.com にアクセスし、マークダウンを貼り付けて共有ボタンをクリックしてください。

認証パスとロールアウト状況

推奨順序:

1. まずブラウザで試す — 最速のデモパス。MCP設定不要。

2. クライアントサポートが確認できたら、ホスト型リモートMCPとブラウザログインを使用する。

3. インタラクティブなログインが利用できない場合は、APIキー / ローカルMCPフォールバックを使用する。

現在のロールアウト状況:

ホスト型リモートMCPのロールアウトに関する注意点:

• https://plsreadme.com/mcp

• https://plsreadme.com/sse

これらのホスト型リモートMCPルートは、コード内のOAuth保護されたブラウザログイン（/authorize、/oauth/token、/oauth/register を含む）の背後で稼働しています。

運用上の注意点:

• D1の doc_create_events は、ウェブ、ホスト型MCP、ローカルMCPフロー全体における正規の作成属性テーブルです。

• docs.raw_view_count はすべてのレンダリングヒットを追跡し、docs.view_count は人間による閲覧と推定されるものに限定されます。

• 本番環境のクエリセットと対応手順については docs/runbooks/auth-surface-monitoring.md を参照してください。

• アクセストークンの有効期限は約 1時間 です。

• リフレッシュトークンの有効期限は約 30日 です。

• 同じクライアントを再接続すると、古い権限は置き換えられます。

• ウェブサイトからサインアウトしても、既存のエディター権限は自動的に取り消されません。

• このリポジトリは、OAUTH_KV という名前のCloudflare Workers KVバインディングに接続されています。

クライアントでブラウザログインが利用できない場合は、/my-links から個人用APIキーを作成し、ホスト型リモートヘッダーフォールバックまたはローカルの npx -y plsreadme-mcp パッケージを使用してください。

ウェブサイトデモの信頼モデル:

• /api/create-link での匿名ウェブサイト作成には、短期間のブラウザ検証権限が必要です。

• サインイン済みのウェブサイト作成ではその権限をスキップし、摩擦を最小限に抑えます。

• 作成後のUIは アカウントに保存、エディターを接続、リンクをコピー に分岐します。

API

curl -X POST https://plsreadme.com/api/render \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello World\n\nThis is my doc."}'

{
  "id": "abc123def456",
  "url": "https://plsreadme.com/v/abc123def456",
  "raw_url": "https://plsreadme.com/v/abc123def456/raw",
  "admin_token": "sk_..."
}

admin_token を保存してください。編集や削除に必要です：

# Update
curl -X PUT https://plsreadme.com/v/abc123def456 \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Updated content"}'

# Delete
curl -X DELETE https://plsreadme.com/v/abc123def456 \
  -H "Authorization: Bearer sk_..."

バージョンタイムライン + 安全な復元

AI反復サイクル中のリビジョンコンテキストを確認するには、タイムラインエンドポイントを使用します：

curl https://plsreadme.com/v/abc123def456/versions

{
  "id": "abc123def456",
  "current_version": 5,
  "total_versions": 5,
  "versions": [
    { "version": 5, "is_current": true, "raw_url": "https://plsreadme.com/v/abc123def456/raw" },
    { "version": 4, "is_current": false, "raw_url": "https://plsreadme.com/v/abc123def456/raw?version=4" }
  ]
}

AIの編集でドキュメントが退行した場合は、以前のスナップショットを復元します（アーカイブ優先、非破壊的）：

curl -X POST https://plsreadme.com/v/abc123def456/restore \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"version": 4}'

復元は更新と同様にレート制限（現在、アクターキーあたり 60回/時間）が適用され、悪用を防止します。

認証済みClerkユーザーが所有するドキュメントの場合、更新・削除・復元には所有者セッションも必要です（ユーザー間での改ざん防止）。一方、匿名ドキュメントは admin_token のみで引き続き動作します。

レビューモードの使用上の注意（現在のドラフト優先、タイムラインはオンデマンド）

ドキュメントビューアーはコメントレビューコントロールを公開しています：

• 現在のドラフト — 最新のドキュメントバージョンに関連付けられたコメントのみを表示します（ドキュメントに複数のバージョンがある場合のデフォルト）。

• タイムライン — バージョンを横断した完全なコメント履歴を表示します。

APIから直接同じモードを取得することも可能です：

# Latest-version comments only
curl "https://plsreadme.com/api/comments/abc123def456?view=current"

# Full timeline comments (default API behavior)
curl "https://plsreadme.com/api/comments/abc123def456?view=all"

ビューアーリンクは、共有可能なレビューコンテキストのためにURLにモードを保持します：

• https://plsreadme.com/v/abc123def456?view=current

• https://plsreadme.com/v/abc123def456?view=timeline

レガシーな匿名リンクをサインイン済みアカウントに請求するには：

curl -X POST https://plsreadme.com/api/auth/claim-link \
  -H "Authorization: Bearer <clerk-session-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"id":"abc123def456","adminToken":"sk_..."}'

MCP (AIエディター)

現在の推奨事項：

• クライアントがクリーンにサポートしている場合は、ブラウザログイン付きのホスト型リモートMCPを使用する

• リモート認証が利用できない、またはクライアントで使いにくい場合は、個人用APIキーフォールバックを使用する

• 最も安全なstdioパスとして、PLSREADME_API_KEY を使用したローカルの plsreadme-mcp パッケージを使用する

エディターをplsreadmeに接続し、自然言語でドキュメントを共有しましょう：

*"このREADMEをplsreadmeリンクとして共有して" *"私のPRDを共有可能なページにして" *"この会議メモを読みやすいリンクにして"

/versions を使用したMCP/エージェントの自動レビューループ

反復的なAIライティングフロー（ドラフト → 批評 → 修正）では、エージェントは /v/:id/versions を信頼できる情報源として利用できます：

1. 人間用の正規の読み取り可能URL (/v/:id) を維持する。

2. 反復の間に /v/:id/versions をポーリングする。

3. current_version と最後にレビューされたバージョンを比較する。

4. 変更されている場合、最新バージョンの raw_url を取得してレビューチェックを実行する。

5. 品質が低下した場合は、必要に応じて管理者トークン + 所有者セッションで /v/:id/restore をトリガーする。

これにより、HTMLをスクレイピングすることなく、自動化された決定論的なリビジョントラッキングが可能になります。

完全なプレイブックについては docs/ai-iteration-versioning.md を参照してください。

🔌 MCP設定

クライアント互換性マトリックス

2026年4月5日現在：

ホスト型リモートログイン（対応クライアント）

Claude Code:

claude mcp add --transport http plsreadme https://plsreadme.com/mcp

Cursor:

{
  "mcpServers": {
    "plsreadme": {
      "url": "https://plsreadme.com/mcp"
    }
  }
}

VS Code:

{
  "servers": {
    "plsreadme": {
      "type": "http",
      "url": "https://plsreadme.com/mcp"
    }
  }
}

Windsurf:

{
  "mcpServers": {
    "plsreadme": {
      "serverUrl": "https://plsreadme.com/mcp"
    }
  }
}

ライフサイクルの注意点：

• アクセストークンのTTLは約 1時間 です。

• リフレッシュトークンのTTLは約 30日 です。

• 同じクライアントを再接続すると、古い権限は置き換えられます。

• サインアウトはウェブサイトのセッションを終了させますが、既存のエディター権限を自動的に取り消すことはありません。

• ホスト型エディター権限の監査や取り消しには GET /api/auth/mcp-grants および DELETE /api/auth/mcp-grants/:grantId を使用してください。

クライアントがブラウザログインをサポートしている場合は、このパスを優先してください。最もクリーンな設定であり、所有ドキュメントがウェブサイトのアカウントに自動的に紐付けられます。

ホスト型リモートAPIキーフォールバック

まず https://plsreadme.com/my-links から個人用APIキーを作成し、以下のいずれかを使用してください：

Claude Code:

claude mcp add --transport http \
  --header "Authorization: Bearer $PLSREADME_API_KEY" \
  plsreadme-api https://plsreadme.com/mcp

Cursor:

{
  "mcpServers": {
    "plsreadme-api": {
      "url": "https://plsreadme.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PLSREADME_API_KEY}"
      }
    }
  }
}

VS Code:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "plsreadme-api-key",
      "description": "plsreadme personal API key",
      "password": true
    }
  ],
  "servers": {
    "plsreadme-api": {
      "type": "http",
      "url": "https://plsreadme.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:plsreadme-api-key}"
      }
    }
  }
}

Windsurf:

{
  "mcpServers": {
    "plsreadme-api": {
      "serverUrl": "https://plsreadme.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PLSREADME_API_KEY}"
      }
    }
  }
}

Rawリモートエンドポイントユーザー：

curl -i https://plsreadme.com/mcp \
  -H "Authorization: Bearer $PLSREADME_API_KEY"

ローカルnpmフォールバック

Claude Code:

claude mcp add --transport stdio \
  --env PLSREADME_API_KEY=$PLSREADME_API_KEY \
  plsreadme -- npx -y plsreadme-mcp

Cursor: ~/.cursor/mcp.json に追加：

{
  "mcpServers": {
    "plsreadme": {
      "command": "npx",
      "args": ["-y", "plsreadme-mcp"],
      "env": {
        "PLSREADME_API_KEY": "${env:PLSREADME_API_KEY}"
      }
    }
  }
}

VS Code: .vscode/mcp.json に追加：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "plsreadme-api-key",
      "description": "plsreadme personal API key",
      "password": true
    }
  ],
  "servers": {
    "plsreadme": {
      "command": "npx",
      "args": ["-y", "plsreadme-mcp"],
      "env": {
        "PLSREADME_API_KEY": "${input:plsreadme-api-key}"
      }
    }
  }
}

Claude Desktop: claude_desktop_config.json に追加：

{
  "mcpServers": {
    "plsreadme": {
      "command": "npx",
      "args": ["-y", "plsreadme-mcp"],
      "env": {
        "PLSREADME_API_KEY": "<paste-your-personal-api-key>"
      }
    }
  }
}

Windsurf: ~/.codeium/windsurf/mcp_config.json に追加：

{
  "mcpServers": {
    "plsreadme": {
      "command": "npx",
      "args": ["-y", "plsreadme-mcp"],
      "env": {
        "PLSREADME_API_KEY": "${env:PLSREADME_API_KEY}"
      }
    }
  }
}

注意点：

• ローカルstdioはデフォルトで PLSREADME_API_KEY を期待するため、新しいドキュメントは所有権が設定されます。

• 明示的なレガシー匿名モードは PLSREADME_ALLOW_ANONYMOUS=1 で引き続き存在します。

• https://plsreadme.com/my-links からキーを作成してください。

既存の匿名MCP設定の移行

すでに plsreadme-mcp を匿名で使用していた場合：

1. /my-links から個人用APIキーを作成します。

2. MCPクライアント設定に PLSREADME_API_KEY を追加します。

3. PLSREADME_ALLOW_ANONYMOUS=1 は、古いワークフローの一時的な互換性維持のためだけに保持してください。

4. 古い匿名リンクの admin_token をまだ持っている場合は、後で /api/auth/claim-link で請求してください。

移行ルールはシンプルです：

• 新しい自動作成/エディター作成はデフォルトで所有権が設定されるべきです。

• 匿名ローカルMCPは現在レガシー専用であり、明示的です。

• ウェブサイトのデモパスは、エディター認証が厳格化されてもゼロ設定のままです。

add-m