What can you do with this server?

The plsreadme server lets you share, manage, and track markdown documents as permanent, beautifully rendered web pages directly from your AI editor or agent. * Share documents: Upload local markdown files or plain text as permanent shareable URLs (plsrd.me/v/xxx); plain text is auto-formatted into clean markdown via AI conversion * Update & delete: Replace content or permanently remove shared documents using their ID or file path; admin tokens are resolved automatically from the local .plsreadme record * Track shared links: List all documents tracked locally with their IDs, titles, URLs, and source file paths * Version control: Access full revision timelines, restore previous snapshots (archive-first, non-destructive), and manage revision history * Collaboration: Enable inline paragraph comments with review modes (Current draft vs. Timeline) * Authentication: Clerk-based user ownership, dashboard access, and legacy anonymous link claiming * Raw access: Download original markdown from any shared link * Rendering: Mobile-responsive pages with clean typography and dark mode support * MCP compatibility: Works with Claude, Cursor, VS Code, and other AI editors * Rate limits: Upload (30/hr), update/restore (60/hr), AI convert (10/hr)

Which integrations are available for this server?

Integrates with Clerk for user authentication, managing document ownership, and facilitating the claiming of legacy anonymous links. Supports document ownership and user identity management through GitHub-based authentication. Supports document ownership and user identity management through Google-based authentication. Converts Markdown text or files into shareable, rendered web pages with features like dark mode, version history, and inline commenting.

de en es ja ko ru zh

plsreadme

by FacundoLucci

Overview Schema Related Servers Score Discussions

TypeScript

The Problem

You wrote a README, a PRD, meeting notes, or an API doc in markdown. Now you need to share it with someone who doesn't have a markdown renderer, doesn't use GitHub, or just needs a clean link they can open in a browser.

plsreadme turns any markdown into a permanent, beautifully rendered web page in one step. No accounts. No sign-ups. No friction.

Related MCP server: slideless-mcp

✨ Features

Instant sharing — Paste markdown or upload a file, get a plsrd.me link
Beautiful rendering — Clean typography, dark mode, mobile-responsive
Inline comments — Readers can click any paragraph and leave feedback
Review mode (current vs timeline) — Multi-version docs default to Current draft feedback with one-click access to full Timeline history
AI auto-formatting — Throw raw text at it; it comes out as clean markdown
MCP server — Share docs directly from Claude, Cursor, VS Code, or any MCP client
OpenClaw skill — Available on ClawHub for AI agent workflows
Short links — Every doc gets a compact plsrd.me/v/xxx URL
Raw access — Download the original .md file from any shared link
Version timeline + safe restore — /v/:id/versions + /v/:id/history + archive-first restore API for fast rollback
Clerk auth foundation — GitHub/Google sign-in wiring + Clerk-hosted email fallback + backend auth verification utilities
Ownership model (Phase 2) — docs can be linked to a Clerk user (owner_user_id) while preserving anonymous flows
My Links dashboard (Phase 3) — authenticated /my-links page with search/sort/pagination and quick copy/open actions
Legacy link claiming (Phase 4) — signed-in users can claim older anonymous links by proving the original admin_token
Zero config website demo — No account or API key needed to try it in the browser

🚀 Quick Start

Web

Go to plsreadme.com, paste your markdown, click share.

Auth Paths And Rollout State

Recommendation order:

Try in browser first — fastest demo path, no MCP setup required.
Use hosted remote MCP with browser login when client support is verified.
Use API key / local MCP fallback when interactive login is unavailable.

Current rollout state:

Journey	Status today	Ownership rule	Source tag
Anonymous website demo	Available now via browser-verified demo flow	`owner_user_id = NULL` until user later saves/claims the doc	`web_demo`
Signed-in website create	Available now	doc is created with the signed-in Clerk user as owner	`web_signed_in`
Hosted remote MCP with browser login	Available now in supported clients	creates owned docs for the signed-in user after browser login	`mcp_remote_login`
Hosted remote MCP with API key	Available now as the compatibility fallback	creates owned docs for the API key owner	`mcp_remote_api_key`
Local npm MCP with API key	Available now and recommended for local stdio setups	creates owned docs for the API key owner	`mcp_local_api_key`
Local npm MCP anonymous fallback	Still available only with explicit opt-in	remains anonymous unless later claimed/saved	`mcp_local_anonymous`

Hosted remote MCP rollout notes:

https://plsreadme.com/mcp
https://plsreadme.com/sse

Those hosted remote MCP routes are live behind OAuth-protected browser login in code, including /authorize, /oauth/token, and /oauth/register.

Operational notes:

D1 doc_create_events is the canonical create-attribution table across web, hosted MCP, and local MCP flows.
docs.raw_view_count tracks every render hit, while docs.view_count is reserved for likely-human reads.
See docs/runbooks/auth-surface-monitoring.md for the production query set and response steps.
access tokens last about 1 hour
refresh tokens last about 30 days
reconnecting the same client replaces the older grant
signing out of the website does not revoke an existing editor grant by itself
this repo is now wired to a dedicated Cloudflare Workers KV binding named OAUTH_KV

When browser login is not available in your client, create a personal API key from /my-links and use either the hosted remote header fallback or the local npx -y plsreadme-mcp package.

Website demo trust model today:

anonymous website creates on /api/create-link require a short-lived browser verification grant
signed-in website creates skip that grant and stay friction-light
post-create UI now branches into Save to my account, Connect your editor, and Copy link

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

Save the admin_token — you'll need it to edit or delete:

# 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_..."

Version timeline + safe restore

Use the timeline endpoint to review revision context during AI iteration cycles:

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

If an AI edit regresses the doc, restore a prior snapshot (archive-first, non-destructive):

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

Restore is rate-limited similarly to updates (currently 60/hour per actor key) to reduce abuse.

For docs owned by an authenticated Clerk user, update/delete/restore also require that owner session (to prevent cross-user mutation), while anonymous docs continue to work with admin_token only.

Review mode usage notes (Current draft first, Timeline on demand)

The document viewer now exposes comment review controls:

Current draft — shows only comments tied to the latest doc version (default when a doc has multiple versions).
Timeline — shows the full cross-version comment history.

You can fetch the same modes directly from the 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"

Viewer links persist the mode in the URL for shareable review context:

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

To claim a legacy anonymous link into your signed-in account:

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 Editors)

Current recommendation today:

use hosted remote MCP with browser login when your client supports it cleanly
use personal API key fallback when remote auth is unavailable or awkward in that client
use the local plsreadme-mcp package with PLSREADME_API_KEY for the safest stdio path

Connect your editor to plsreadme and share docs with natural language:

"Share this README as a plsreadme link" "Turn my PRD into a shareable page" "Make these meeting notes into a readable link"

MCP/agent auto-review loop with `/versions`

For iterative AI writing flows (draft → critique → revise), agents can consume /v/:id/versions as the source of truth:

Keep the canonical readable URL (/v/:id) for humans.
Poll /v/:id/versions between iterations.
Compare current_version to the last reviewed version.
If changed, fetch raw_url for the newest version and run review checks.
If quality regresses, optionally trigger /v/:id/restore with admin token + owner session.

This gives automation deterministic revision tracking without scraping HTML.

See docs/ai-iteration-versioning.md for a full playbook.

🔌 MCP Setup

Client compatibility matrix

Current as of April 5, 2026:

Client	Recommended path	Browser login support	API key fallback	Notes
Claude Code	hosted remote MCP first	verified live	yes	best supported remote flow; local stdio with `PLSREADME_API_KEY` also works well
Cursor	hosted remote MCP first	documented, but build-dependent in practice	yes	use headers if your build does not surface the OAuth prompt
VS Code	hosted remote MCP when available	configuration exists, rollout varies by build	yes	`type: "http"` plus header fallback works when login UX is absent
Windsurf	hosted remote MCP when available	documented remote support	yes	use `serverUrl` + headers when browser auth is not exposed yet
Claude Desktop	local npm MCP	no verified remote browser flow here	yes	prefer stdio + `PLSREADME_API_KEY`
Raw HTTP / scripts	hosted remote header mode	no	yes	send `Authorization: Bearer $PLSREADME_API_KEY` directly

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

Lifecycle notes:

access token TTL is about 1 hour
refresh token TTL is about 30 days
reconnecting the same client replaces the older grant
sign out ends the website session but does not automatically revoke an existing editor grant
use GET /api/auth/mcp-grants and DELETE /api/auth/mcp-grants/:grantId to audit or revoke hosted editor grants

If your client supports browser login, prefer this path. It is the cleanest setup and keeps owned docs tied to your website account automatically.

Hosted Remote API Key fallback

Create a personal API key from https://plsreadme.com/my-links first, then use one of these:

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 remote endpoint users:

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

Local npm fallback

Claude Code:

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

Cursor: Add to ~/.cursor/mcp.json:

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

VS Code: Add to .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: Add to claude_desktop_config.json:

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

Windsurf: Add to ~/.codeium/windsurf/mcp_config.json:

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

Notes:

local stdio now expects PLSREADME_API_KEY by default so new docs are owned
explicit legacy anonymous mode still exists with PLSREADME_ALLOW_ANONYMOUS=1
create your key from https://plsreadme.com/my-links

Migrating existing anonymous MCP setups

If you already used plsreadme-mcp anonymously:

Create a personal API key from /my-links.
Add PLSREADME_API_KEY to your MCP client config.
Keep PLSREADME_ALLOW_ANONYMOUS=1 only as a temporary compatibility crutch for old workflows.
Claim older anonymous links later with /api/auth/claim-link if you still have their admin_token.

The migration rule is simple:

new automated/editor creates should be owned by default
anonymous local MCP is now legacy-only and explicit
the website demo path remains zero-setup even while editor auth gets stricter

add-mcp

npx add-mcp plsreadme-mcp

OpenClaw

clawhub install plsreadme

Docker (for MCP registries / listing checks)

Build and run the stdio MCP server in a clean container:

docker build -t plsreadme-mcp:local .
docker run --rm -i plsreadme-mcp:local

The containerized server uses stdio (no ports, no env vars required).

🛠 MCP Tools

Tool	What it does
`plsreadme_share_file`	Share a local file by path → returns shareable link. Re-sharing updates the same link.
`plsreadme_share_text`	Share markdown or plain text directly → returns shareable link
`plsreadme_update`	Update an existing doc with new content (by ID or file path)
`plsreadme_delete`	Delete a shared doc permanently (by ID or file path)
`plsreadme_list`	List all documents you've shared from this project

Prompts:

share-document — Guided flow to share content as a readable link
refactor-and-share — Uses your AI model to refactor raw text into polished markdown, then shares it

Plain text input? No problem — the MCP auto-structures it into markdown, or you can use the refactor-and-share prompt to leverage your AI's reasoning for a polished result.

.plsreadme Record File

The MCP server tracks your shared documents in a .plsreadme JSON file in your project root. This stores document IDs, URLs, and admin tokens needed for editing and deleting.

⚠️ Add .plsreadme to your .gitignore — it contains admin tokens. The tool will warn you if it's missing.

🏗 Architecture

Built on Cloudflare's edge stack for speed everywhere:

┌─────────────┐     ┌──────────────────┐     ┌─────────┐
│  Web / API  │────▶│  Cloudflare      │────▶│   R2    │
│  MCP Client │     │  Workers (Hono)  │     │ (docs)  │
└─────────────┘     └──────────────────┘     └─────────┘
                           │
                    ┌──────┴──────┐
                    │     D1      │
                    │ (metadata)  │
                    └─────────────┘

Hono — Lightweight web framework on Workers
Cloudflare D1 — SQLite at the edge for metadata, comments, analytics
Cloudflare R2 — Object storage for markdown documents
Durable Objects — Stateful MCP server endpoint
Workers AI — Optional fallback for text-to-markdown conversion

📁 Project Structure

plsreadme/
├── worker/
│   ├── index.ts              # Main worker entry
│   ├── auth.ts               # Clerk JWT verification utilities/middleware
│   ├── routes/
│   │   ├── auth.ts           # Auth config/session/protected identity endpoints
│   │   ├── docs.ts           # Document creation & rendering
│   │   ├── comments.ts       # Inline commenting system
│   │   ├── convert.ts        # AI text→markdown conversion
│   │   ├── analytics.ts      # View tracking
│   │   ├── links.ts          # Short link handling
│   │   └── waitlist.ts       # Waitlist & notifications
│   ├── mcp-agent.ts          # Remote MCP server (Durable Object)
│   └── types.ts              # TypeScript types
├── packages/
│   └── mcp/                  # npm package: plsreadme-mcp
│       └── src/index.ts      # MCP server (stdio transport)
├── public/                   # Static assets & landing pages
├── db/
│   └── schema.sql            # D1 database schema
├── docs/
│   ├── ai-iteration-versioning.md # Version timeline/restore patterns for human + agent loops
│   ├── auth-clerk.md              # Auth setup + environment checklist
│   └── runbooks/
│       └── legacy-link-claim-rollout.md
├── skill/
│   └── plsreadme/            # OpenClaw agent skill
└── wrangler.jsonc             # Cloudflare Workers config

🔧 Development

# Install dependencies
npm install

# Run locally
npm run dev

# Deploy
npm run deploy

# Bootstrap schema (fresh local DB)
npm run db:migrate:local

# Audit unapplied migrations (remote + local)
npm run db:migrations:status

# Apply migration files explicitly
npm run db:migrations:apply        # remote
npm run db:migrations:apply:local  # local

Ownership phase migration notes:

wrangler.jsonc points migrations_dir to db/migrations, so migration status is auditable with explicit list/apply commands.
Apply db/migrations/004_owner_user_id.sql in existing environments before relying on ownership filters.
Apply db/migrations/007_doc_attribution_telemetry.sql before relying on doc_create_events or raw_view_count.
Legacy rows are intentionally backfilled as owner_user_id = NULL (anonymous/public behavior preserved).
Write routes still run a safe ownership schema ensure step (duplicate-column tolerant) for mixed-env rollout safety.
See docs/migrations.md for the explicit audit/apply workflow.

MCP package release

plsreadme-mcp is published from packages/mcp by pushing an mcp-v* tag (see .github/workflows/publish-mcp.yml).

cd packages/mcp
npm version patch   # or minor/major
cd ../..
git add packages/mcp/package.json packages/mcp/package-lock.json
VERSION=$(node -p "require('./packages/mcp/package.json').version")
git commit -m "chore(mcp): release v${VERSION}"
git tag "mcp-v${VERSION}"
# push commit + tag from your machine to trigger npm publish workflow

Environment Variables

Start from .env.example and set values in your local/dev/prod environment.

Cloudflare tip: non-sensitive values can live in vars; sensitive values should be set with wrangler secret put.

Variable	Required	Description
`OPENAI_API_KEY`	No	OpenAI key for `/api/convert` text→markdown
`DISCORD_WEBHOOK_URL`	No	Waitlist signup notifications
`DISCORD_LINK_WEBHOOK_URL`	No	New link creation notifications
`RESEND_API_KEY`	No	Email notifications
`NOTIFICATION_EMAIL`	No	Email recipient for notifications
`CLERK_PUBLISHABLE_KEY`	For auth	Clerk publishable key for frontend auth wiring (social + email fallback)
`CLERK_JWT_ISSUER`	For auth	Clerk JWT issuer used by worker verification
`CLERK_JWT_AUDIENCE`	Optional	Expected audience claim for Clerk JWTs
`CLERK_SIGN_IN_URL`	Optional	Clerk-hosted sign-in URL hint (default `/sign-in`)
`CLERK_SIGN_UP_URL`	Optional	Clerk-hosted sign-up URL hint (default `/sign-up`)
`CLERK_SECRET_KEY`	Optional	Reserved for future server-side Clerk integrations

If OAuth credentials are not configured yet, users can still click Sign in / Use email instead and complete auth through the Clerk-hosted email flow immediately.

Frontend auth shell notes:

/app.html and /my-links use public/clerk-auth-shell.js (Clerk-native browser SDK wiring).
Authenticated frontend API calls should read bearer tokens through window.plsreadmeGetAuthToken().

The core sharing functionality still requires zero configuration. Clerk auth, AI conversion, and notifications are opt-in.

For the full auth setup checklist, see docs/auth-clerk.md. For rollout + smoke checks, see docs/runbooks/mcp-auth-rollout-checklist.md.

📊 Limits

Limit	Value
Max document size	200 KB
Upload rate limit	30/hour per actor key
Update/restore rate limit	60/hour per actor key
AI convert rate limit	10/hour per IP
Link lifetime	Permanent

🤝 Contributing

Feature ideas? Bug reports? Open an issue.

PRs welcome for bug fixes and improvements.

📄 License

MIT — do whatever you want with it.

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

Name	Required	Description	Default
`id`	No	Document ID to delete.
`file_path`	No	Original 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

Name	Required	Description	Default
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

Name	Required	Description	Default
`file_path`	Yes	Path 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

Name	Required	Description	Default
`markdown`	Yes	Content to share. Markdown preferred, but plain text accepted.
`title`	No	Optional 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

Name	Required	Description
`id`	No	Document ID to update.
`file_path`	No	Original file path (looks up the linked doc).
`markdown`	Yes	New 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.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

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

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

artidrop A
ai.artidrop
Publish HTML, Markdown, and multi-file sites as shareable URLs instantly via MCP.
Content Management Systems Developer Tools
42
mkdshare.DEV A
io.github.PhilipAnd
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
Content Management Systems Documentation Access Developer Tools
112
Slideless
ai.slideless
List, share, upload, and manage Slideless HTML presentations from any MCP host.
Content Management Systems Workplace & Productivity
2
Context Awesome A
io.github.bh-rat
MCP server for accessing curated awesome list documentation
Documentation Access Research & Data
2259

Related MCP Servers

rustypaste-mcp-server
File Systems Cloud Storage App Automation
rukh-debug
F
license
A
quality
D
maintenance
An MCP server that wraps the rustypaste API, allowing users to upload text, files, and URLs to a rustypaste instance. It supports features such as single-use links, file expiration, and URL shortening.
Updated 6 months ago (2026-03-06 03:44 UTC)
7
47
slideless-mcpofficial
Content Management Systems Workplace & Productivity
slideless-ai
F
license
Not graded
quality
D
maintenance
MCP server that wraps the Slideless HTTP API as tools for listing, sharing, uploading, and managing HTML presentations from any MCP host without installing the CLI.
Updated 3 months ago (2026-06-08 20:16 UTC)
PasteAIofficial
Note Taking Content Management Systems
pasteai
A
license
A
quality
B
maintenance
An MCP server that lets AI publish markdown documents to a clean, themed web UI. One tool call creates a shareable doc.
Updated 2 months ago (2026-07-19 05:22 UTC)
8
4
MIT
wiki-mcp
Note Taking File Systems Knowledge & Memory
icarus-inte01
F
license
Not graded
quality
C
maintenance
MCP server for managing a personal markdown wiki. Provides search, navigation, read, write, delete, and move tools with automatic index.md management.
Updated 3 months ago (2026-06-16 15:23 UTC)

Appeared in Searches

Markdown MCP (Model Context Protocol) Server

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/FacundoLucci/plsreadme'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

The Problem

✨ Features

🚀 Quick Start

Web

Auth Paths And Rollout State

API

Version timeline + safe restore

Review mode usage notes (Current draft first, Timeline on demand)

MCP (AI Editors)

MCP/agent auto-review loop with /versions

🔌 MCP Setup

Client compatibility matrix

Hosted Remote Login (supported clients)

Hosted Remote API Key fallback

Local npm fallback

Migrating existing anonymous MCP setups

add-mcp

OpenClaw

Docker (for MCP registries / listing checks)

🛠 MCP Tools

.plsreadme Record File

🏗 Architecture

📁 Project Structure

🔧 Development

MCP package release

Environment Variables

📊 Limits

🤝 Contributing

📄 License

Available Tools

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

slideless-mcpofficial

PasteAIofficial

Appeared in Searches

Latest Blog Posts

MCP directory API

MCP/agent auto-review loop with `/versions`