plsreadme

Проблема

Вы написали README, PRD, заметки о встрече или документацию API в формате markdown. Теперь вам нужно поделиться этим с кем-то, у кого нет рендерера markdown, кто не использует GitHub или кому просто нужна чистая ссылка, которую можно открыть в браузере.

plsreadme превращает любой markdown в постоянную, красиво оформленную веб-страницу за один шаг. Никаких аккаунтов. Никаких регистраций. Никаких сложностей.

✨ Возможности

• Мгновенный обмен — вставьте markdown или загрузите файл, получите ссылку plsrd.me

• Красивый рендеринг — чистая типографика, темная тема, адаптивность для мобильных устройств

• Встроенные комментарии — читатели могут нажать на любой абзац и оставить отзыв

• Режим обзора (текущий vs хронология) — документы с несколькими версиями по умолчанию показывают отзывы к текущему черновику с доступом в один клик к полной истории хронологии

• AI автоформатирование — просто отправьте сырой текст; он превратится в чистый markdown

• MCP-сервер — делитесь документами напрямую из Claude, Cursor, VS Code или любого MCP-клиента

• Навык OpenClaw — доступен на ClawHub для рабочих процессов AI-агентов

• Короткие ссылки — каждый документ получает компактный URL plsrd.me/v/xxx

• Доступ к исходнику — скачайте оригинальный файл .md по любой ссылке

• Хронология версий + безопасное восстановление — /v/:id/versions + /v/:id/history + API восстановления с приоритетом архива для быстрого отката

• Основа на Clerk auth — интеграция входа через GitHub/Google + резервный вариант с email через Clerk + утилиты проверки бэкенд-авторизации

• Модель владения (Фаза 2) — документы могут быть привязаны к пользователю Clerk (owner_user_id) с сохранением анонимных потоков

• Панель «Мои ссылки» (Фаза 3) — аутентифицированная страница /my-links с поиском/сортировкой/пагинацией и быстрыми действиями копирования/открытия

• Присвоение старых ссылок (Фаза 4) — авторизованные пользователи могут заявить права на старые анонимные ссылки, подтвердив оригинальный admin_token

• Демонстрация сайта без настройки — для тестирования в браузере не требуется аккаунт или API-ключ

🚀 Быстрый старт

Веб

Перейдите на plsreadme.com, вставьте свой markdown, нажмите «поделиться».

Пути авторизации и состояние развертывания

Рекомендуемый порядок:

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 дней

• повторное подключение того же клиента заменяет старый грант

• выход из системы на сайте сам по себе не отзывает существующий грант редактора

• этот репозиторий теперь подключен к выделенной привязке Cloudflare Workers KV с именем OAUTH_KV

Когда вход через браузер недоступен в вашем клиенте, создайте личный API-ключ на странице /my-links и используйте либо резервный заголовок удаленного доступа, либо локальный пакет 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-ключ, если удаленная авторизация недоступна или неудобна

• используйте локальный пакет plsreadme-mcp с PLSREADME_API_KEY для самого безопасного пути через stdio

Подключите свой редактор к plsreadme и делитесь документами с помощью естественного языка:

"Поделись этим README как ссылкой plsreadme" "Преврати мой PRD в страницу для общего доступа" "Сделай эти заметки о встрече читаемой ссылкой"

Цикл авто-обзора MCP/агента с /versions

Для итеративных процессов написания AI (черновик → критика → правка) агенты могут использовать /v/:id/versions как источник истины:

1. Сохраняйте канонический читаемый URL (/v/:id) для людей.

2. Опрашивайте /v/:id/versions между итерациями.

3. Сравнивайте current_version с последней проверенной версией.

4. Если есть изменения, получите raw_url для новой версии и запустите проверки.

5. Если качество ухудшилось, при необходимости вызовите /v/:id/restore с admin token + сессией владельца.

Это дает автоматизации детерминированное отслеживание ревизий без парсинга HTML.

См. docs/ai-iteration-versioning.md для полного руководства.

🔌 Настройка MCP

Матрица совместимости клиентов

Актуально на 5 апреля 2026 года:

Удаленный вход (поддерживаемые клиенты)

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-ключом

Сначала создайте личный API-ключ на странице https://plsreadme.com/my-links, затем используйте один из вариантов:

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}"
      }
    }
  }
}

Пользователи удаленных эндпоинтов:

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. Создайте личный API-ключ на странице /my-links.

2. Добавьте PLSREADME_API_KEY в конфигурацию вашего MCP-клиента.

3. Оставьте PLSREADME_ALLOW_ANONYMOUS=1 только как временную костыльную совместимость для старых рабочих процессов.