FacundoLucci/plsreadme
mcp` or `https://plsreadme.com/mcp`).
Ask AI about FacundoLucci/plsreadme
Powered by Claude Β· Grounded in docs
I know everything about FacundoLucci/plsreadme. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
plsreadme
Paste markdown. Get a beautiful, shareable link. Done.
Website Β· MCP Package Β· Request a Feature
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.
β¨ Features
- Instant sharing β Paste markdown or upload a file, get a
plsrd.melink - Beautiful rendering β Clean typography, dark mode, mobile-responsive
- Inline comments β Readers can click any paragraph and leave feedback
- 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/xxxURL - Raw access β Download the original
.mdfile from any shared link - 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-linkspage 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 β No API keys needed for basic usage
π Quick Start
Web
Go to plsreadme.com, paste your markdown, click share.
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_..."
For docs owned by an authenticated Clerk user, update/delete also require that owner session (to prevent cross-user mutation), while anonymous docs continue to work with admin_token only.
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)
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 Setup
Claude Code
claude mcp add plsreadme -- npx -y plsreadme-mcp
Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"]
}
}
}
VS Code
Add to your settings.json:
{
"mcp": {
"servers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"]
}
}
}
}
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"]
}
}
}
Windsurf
{
"mcpServers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"]
}
}
}
Remote MCP (zero install)
Some clients support remote MCP endpoints directly:
https://plsreadme.com/mcp
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 linkrefactor-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/
β βββ 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.jsoncpointsmigrations_dirtodb/migrations, so migration status is auditable with explicit list/apply commands.- Apply
db/migrations/004_owner_user_id.sqlin existing environments before relying on ownership filters. - 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.mdfor 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 withwrangler 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.htmland/my-linksusepublic/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.
π Limits
| Limit | Value |
|---|---|
| Max document size | 200 KB |
| Upload rate limit | 30/hour per IP |
| 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.
Built by Facundo Lucci
