Skip to main content
Glama
deenesjakoruzh
FacundoLucci

plsreadme

by FacundoLucci
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

Проблема

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

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

Related MCP server: slideless-mcp

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

  • Мгновенный обмен — вставьте 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 в качестве резервного варианта, если интерактивный вход недоступен.

Текущее состояние развертывания:

Путь

Статус сегодня

Правило владения

Тег источника

Анонимная демо-версия сайта

Доступно через демо-поток с проверкой в браузере

owner_user_id = NULL до тех пор, пока пользователь не сохранит/заявит права на документ

web_demo

Создание через авторизованный сайт

Доступно сейчас

документ создается с владельцем — авторизованным пользователем Clerk

web_signed_in

Удаленный MCP с входом через браузер

Доступно в поддерживаемых клиентах

создает документы, принадлежащие пользователю после входа через браузер

mcp_remote_login

Удаленный MCP с API-ключом

Доступно как резервный вариант совместимости

создает документы, принадлежащие владельцу API-ключа

mcp_remote_api_key

Локальный npm MCP с API-ключом

Доступно сейчас, рекомендуется для локальных stdio-настроек

создает документы, принадлежащие владельцу API-ключа

mcp_local_api_key

Локальный npm MCP анонимный

Доступно только при явном включении

остается анонимным, пока не будет заявлено/сохранено

mcp_local_anonymous

Примечания по удаленному 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 года:

Клиент

Рекомендуемый путь

Поддержка входа через браузер

Резервный API-ключ

Примечания

Claude Code

сначала удаленный MCP

подтверждено

да

лучший удаленный поток; локальный stdio с PLSREADME_API_KEY также работает хорошо

Cursor

сначала удаленный MCP

задокументировано, зависит от сборки

да

используйте заголовки, если ваша сборка не вызывает OAuth-запрос

VS Code

удаленный MCP, если доступен

конфигурация есть, развертывание зависит от сборки

да

type: "http" плюс резервный заголовок работают, когда UX входа отсутствует

Windsurf

удаленный MCP, если доступен

задокументированная удаленная поддержка

да

используйте serverUrl + заголовки, когда браузерная авторизация еще не открыта

Claude Desktop

локальный npm MCP

нет подтвержденного удаленного потока

да

предпочтительнее stdio + PLSREADME_API_KEY

Raw HTTP / скрипты

удаленный режим заголовков

нет

да

отправляйте Authorization: Bearer $PLSREADME_API_KEY напрямую

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

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 только как временную костыльную совместимость для старых рабочих процессов.

Available Tools

5 tools
plsreadme_deleteA
Destructive

Delete a plsreadme document permanently.

Requires either the document ID or the original file path. Looks up the admin token from the local .plsreadme record file.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoDocument ID to delete.
file_pathNoOriginal file path (looks up the linked doc).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations mark destructiveHint=true. The description adds that deletion is 'permanently' and reveals that the tool 'Looks up the admin token from the local .plsreadme record file,' which is a behavioral dependency beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two succinct sentences: first states the primary action, second provides key constraints. No unnecessary words or repetition. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple delete tool with no output schema, the description covers the core action, permanence, and a prerequisite. The token lookup detail is helpful. It could mention error handling or confirmation, but overall is adequate for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters having descriptions. The description adds the critical constraint that 'Requires either the document ID or the original file path,' clarifying that they are alternatives, which the schema's optionality does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Delete a plsreadme document permanently.' The verb 'Delete' and the resource 'plsreadme document' are specific. The description distinguishes from siblings (list, share, update) as there is no other delete tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a usage prerequisite: requires either document ID or file path. However, it does not specify when not to use this tool or offer alternatives to alternatives to deletion. The guidance is minimal but present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

plsreadme_listA
Read-onlyIdempotent

List all plsreadme documents tracked in the local .plsreadme file.

Shows document IDs, titles, URLs, and source files.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the detail that it reads from a local file, which is useful but not essential beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences that front-load the core action. Every word serves a purpose, and there is no extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list operation with no parameters and no output schema, the description adequately covers behavior (lists all documents) and return fields. It does not mention sorting or pagination, but given the tool's simplicity, this is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters in the input schema, so the description does not need to add parameter details. Schema coverage is 100% by default, and the description provides no contradictory or missing information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifically states the action (list all documents), the resource (plsreadme documents tracked in the local .plsreadme file), and the output fields (IDs, titles, URLs, source files). It clearly distinguishes from sibling operations like delete, share, and update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus its siblings. There is no mention of prerequisites or alternatives, leaving the agent to infer context from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

plsreadme_share_fileB
Read-only

Share a local markdown file as a clean, readable web link on plsreadme.com.

Reads the file, uploads it, and returns a permanent shareable URL. If the file was previously shared, updates the existing link instead of creating a new one.

Tracks links in a local .plsreadme file for future edits and deletes.

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYesPath to the markdown file to share (relative or absolute).

TDQS

B3.4/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description contradicts the annotation 'readOnlyHint=true' by stating it uploads the file and may update existing links, indicating a write operation. This is a serious inconsistency, so score 1 as per rules.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four concise sentences, no redundant information. The first sentence captures the primary purpose, and each subsequent sentence adds relevant detail without excess.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema, the description adequately covers the main behavior: reading, uploading, updating if previously shared, and tracking links. It lacks details on error cases or URL format, but overall sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter 'file_path' is well-described in the schema. The description adds context about reading and uploading the file, but does not significantly add meaning beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool shares a local markdown file as a web link, with specific verb 'Share' and resource 'local markdown file'. It distinguishes from siblings like 'share_text' (which shares raw text) and 'update' (which updates existing links).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a markdown file needs sharing, and mentions updating existing links. However, it does not explicitly exclude other use cases or provide guidance on when not to use this tool versus alternatives like 'share_text' or 'update'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

plsreadme_share_textA
Read-only

Share text as a clean, readable web link on plsreadme.com.

Accepts markdown or plain text. Plain text is auto-structured into markdown before upload. Returns a permanent shareable URL.

Tracks links in a local .plsreadme file for future edits and deletes.

ParametersJSON Schema
NameRequiredDescriptionDefault
markdownYesContent to share. Markdown preferred, but plain text accepted.
titleNoOptional title (auto-detected from first H1 if omitted).

TDQS

A3.8/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations set readOnlyHint=true, but the description describes creating a share link and tracking in a local file, which contradicts that. Description adds context about tracking but fails to resolve the contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences with no wasted words, front-loaded with the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description mentions the return value (permanent URL) and tracking behavior, covering key aspects. Lacks mention of rate limits or authentication, but acceptable for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds value by stating markdown is preferred but plain text accepted, and title is auto-detected if omitted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool shares text as a clean web link, accepts markdown or plain text, and distinguishes from siblings like share_file which handles files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use it (to share text) and implies alternatives by naming siblings, but lacks explicit when-not-to-use or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

plsreadme_updateA
Idempotent

Update an existing plsreadme document with new content.

Requires either the document ID or the original file path. Looks up the admin token from the local .plsreadme record file.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoDocument ID to update.
file_pathNoOriginal file path (looks up the linked doc).
markdownYesNew markdown content.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds context beyond annotations: authentication via local file, alternative identifiers. Consistent with idempotentHint=true and readOnlyHint=false. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, first states action, second details requirements. No redundant information, highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers action, required params, and identification method. Lacks error handling details or return type, but sufficient for a simple update tool with idempotent hint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. Description adds meaning by clarifying id and file_path are alternatives, not both required. Enhances understanding of parameter relationships.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Update' and the resource 'existing plsreadme document'. It distinguishes this tool from siblings (delete, list, share) by specifying content update.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on required parameters (either id or file_path) and mentions a prerequisite (admin token lookup). Could explicitly state when to use vs alternatives, but siblings are distinct actions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.0.1
    • Addedplsreadme_delete
    • Addedplsreadme_list
    • Addedplsreadme_share_file
    • Addedplsreadme_share_text
    • Addedplsreadme_update
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a distinct purpose: delete, list, share file, share text, update. There is no ambiguity as descriptions clearly differentiate them.

Naming Consistency5/5

All tools follow the consistent pattern 'plsreadme_verb' with verbs like delete, list, share_file, share_text, update. Naming is uniform and predictable.

Tool Count5/5

With 5 tools covering the core operations of sharing, listing, updating, and deleting documents, the count is well-scoped and appropriate for the service's purpose.

Completeness4/5

The tool set offers full CRUD-like coverage (create via share, read via list, update, delete) but lacks a direct 'get by ID' tool, though list provides IDs and URLs.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches