plsreadme
Comparte archivos markdown y texto como enlaces web limpios y legibles. Funciona con Cursor, Claude Desktop, VS Code, Windsurf y cualquier cliente MCP.
Documentación
plsreadme
Pega markdown. Obtén un enlace hermoso y compartible. Listo.
Sitio web · Paquete MCP · Solicitar una función
El problema
Escribiste un README, un PRD, notas de reunión o un documento de API en markdown. Ahora necesitas compartirlo con alguien que no tiene un renderizador de markdown, no usa GitHub, o simplemente necesita un enlace limpio que pueda abrir en un navegador.
plsreadme convierte cualquier markdown en una página web permanente y bellamente renderizada en un solo paso. Sin cuentas. Sin registros. Sin fricción.
✨ Características
- Compartición instantánea — Pega markdown o sube un archivo, obtén un enlace
plsrd.me - Renderizado hermoso — Tipografía limpia, modo oscuro, responsive para móviles
- Comentarios en línea — Los lectores pueden hacer clic en cualquier párrafo y dejar comentarios
- Modo de revisión (actual vs línea de tiempo) — Los documentos multiversión usan por defecto comentarios del Borrador actual con acceso con un clic al historial completo de la Línea de tiempo
- Autoformato con IA — Lánzale texto sin procesar; sale como markdown limpio
- Servidor MCP — Comparte documentos directamente desde Claude, Cursor, VS Code o cualquier cliente MCP
- Habilidad OpenClaw — Disponible en ClawHub para flujos de trabajo de agentes de IA
- Enlaces cortos — Cada documento obtiene una URL compacta
plsrd.me/v/xxx - Acceso sin procesar — Descarga el archivo
.mdoriginal desde cualquier enlace compartido - Línea de tiempo de versiones + restauración segura —
/v/:id/versions+/v/:id/history+ API de restauración con archivo primero para reversión rápida - Base de autenticación Clerk — Conexión de inicio de sesión con GitHub/Google + respaldo de correo alojado por Clerk + utilidades de verificación de autenticación en el backend
- Modelo de propiedad (Fase 2) — los documentos pueden vincularse a un usuario de Clerk (
owner_user_id) mientras se preservan los flujos anónimos - Panel de Mis enlaces (Fase 3) — página
/my-linksautenticada con búsqueda/orden/paginación y acciones rápidas de copiar/abrir - Reclamación de enlaces heredados (Fase 4) — los usuarios con sesión iniciada pueden reclamar enlaces anónimos antiguos demostrando el
admin_tokenoriginal - Demo del sitio web sin configuración — No se necesita cuenta ni clave API para probarlo en el navegador
🚀 Inicio rápido
Web
Ve a plsreadme.com, pega tu markdown, haz clic en compartir.
Rutas de autenticación y estado de implementación
Orden de recomendación:
- Prueba primero en el navegador — la ruta de demostración más rápida, sin necesidad de configuración de MCP.
- Usa MCP remoto alojado con inicio de sesión en el navegador cuando se verifique la compatibilidad del cliente.
- Usa clave API / respaldo MCP local cuando el inicio de sesión interactivo no esté disponible.
Estado de implementación actual:
| Recorrido | Estado hoy | Regla de propiedad | Etiqueta de origen |
|---|---|---|---|
| Demo anónima del sitio web | Disponible ahora mediante flujo de demostración verificado por navegador | owner_user_id = NULL hasta que el usuario guarde o reclame el documento más tarde | web_demo |
| Creación en el sitio web con sesión iniciada | Disponible ahora | el documento se crea con el usuario de Clerk con sesión iniciada como propietario | web_signed_in |
| MCP remoto alojado con inicio de sesión en el navegador | Disponible ahora en clientes compatibles | crea documentos con propietario para el usuario con sesión iniciada después del inicio de sesión en el navegador | mcp_remote_login |
| MCP remoto alojado con clave API | Disponible ahora como respaldo de compatibilidad | crea documentos con propietario para el propietario de la clave API | mcp_remote_api_key |
| MCP npm local con clave API | Disponible ahora y recomendado para configuraciones stdio locales | crea documentos con propietario para el propietario de la clave API | mcp_local_api_key |
| Respaldo anónimo MCP npm local | Aún disponible solo con aceptación explícita | permanece anónimo a menos que se reclame o guarde más tarde | mcp_local_anonymous |
Notas de implementación del MCP remoto alojado:
https://plsreadme.com/mcphttps://plsreadme.com/sse
Esas rutas de MCP remoto alojado están activas detrás de inicio de sesión en el navegador protegido por OAuth en el código, incluyendo /authorize, /oauth/token y /oauth/register.
Notas operativas:
-
D1
doc_create_eventses la tabla canónica de atribución de creación en flujos web, MCP alojado y MCP local. -
docs.raw_view_countrastrea cada visita de renderizado, mientras quedocs.view_countestá reservado para lecturas probablemente humanas. -
Consulta
docs/runbooks/auth-surface-monitoring.mdpara el conjunto de consultas de producción y los pasos de respuesta. -
los tokens de acceso duran aproximadamente
1 hour -
los tokens de actualización duran aproximadamente
30 days -
reconectar el mismo cliente reemplaza la concesión anterior
-
cerrar sesión en el sitio web no revoca por sí solo una concesión de editor existente
-
este repositorio ahora está conectado a un enlace dedicado de Cloudflare Workers KV llamado
OAUTH_KV
Cuando el inicio de sesión en el navegador no esté disponible en tu cliente, crea una clave API personal desde /my-links y usa el respaldo de encabezado remoto alojado o el paquete npx -y plsreadme-mcp local.
Modelo de confianza de la demo del sitio web hoy:
- las creaciones anónimas en el sitio web en
/api/create-linkrequieren una concesión de verificación de navegador de corta duración - las creaciones con sesión iniciada en el sitio web omiten esa concesión y se mantienen sin fricción
- la interfaz posterior a la creación ahora se divide en
Save to my account,Connect your editoryCopy 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_..."
}
Guarda el admin_token — lo necesitarás para editar o eliminar:
# 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_..."
Línea de tiempo de versiones + restauración segura
Usa el endpoint de línea de tiempo para revisar el contexto de revisiones durante ciclos de iteración de IA:
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" }
]
}
Si una edición de IA degrada el documento, restaura una instantánea anterior (archivo primero, no destructivo):
curl -X POST https://plsreadme.com/v/abc123def456/restore \
-H "Authorization: Bearer sk_..." \
-H "Content-Type: application/json" \
-d '{"version": 4}'
La restauración tiene límite de velocidad similar a las actualizaciones (actualmente 60/hour por clave de actor) para reducir el abuso.
Para documentos propiedad de un usuario de Clerk autenticado, actualizar/eliminar/restaurar también requieren esa sesión de propietario (para prevenir mutación entre usuarios), mientras que los documentos anónimos continúan funcionando solo con admin_token.
Notas de uso del modo de revisión (Borrador actual primero, Línea de tiempo bajo demanda)
El visor de documentos ahora expone controles de revisión de comentarios:
- Borrador actual — muestra solo comentarios vinculados a la versión más reciente del documento (predeterminado cuando un documento tiene múltiples versiones).
- Línea de tiempo — muestra el historial completo de comentarios entre versiones.
Puedes obtener los mismos modos directamente desde la 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"
Los enlaces del visor persisten el modo en la URL para contexto de revisión compartible:
https://plsreadme.com/v/abc123def456?view=currenthttps://plsreadme.com/v/abc123def456?view=timeline
Para reclamar un enlace anónimo heredado en tu cuenta con sesión iniciada:
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 (Editores de IA)
Recomendación actual:
- usa MCP remoto alojado con inicio de sesión en el navegador cuando tu cliente lo admita limpiamente
- usa el respaldo de clave API personal cuando la autenticación remota no esté disponible o sea incómoda en ese cliente
- usa el paquete
plsreadme-mcplocal conPLSREADME_API_KEYpara la ruta stdio más segura
Conecta tu editor a plsreadme y comparte documentos con lenguaje natural:
"Comparte este README como un enlace de plsreadme" "Convierte mi PRD en una página compartible" "Haz que estas notas de reunión sean un enlace legible"
Bucle de auto-revisión MCP/agente con /versions
Para flujos de escritura iterativos con IA (borrador → crítica → revisión), los agentes pueden consumir /v/:id/versions como fuente de verdad:
- Mantén la URL canónica legible (
/v/:id) para humanos. - Consulta
/v/:id/versionsentre iteraciones. - Compara
current_versioncon la última versión revisada. - Si cambió, obtén
raw_urlpara la versión más reciente y ejecuta verificaciones de revisión. - Si la calidad retrocede, opcionalmente activa
/v/:id/restorecon token de administrador + sesión de propietario.
Esto le da a la automatización un seguimiento de revisiones determinista sin raspar HTML.
Consulta docs/ai-iteration-versioning.md para un manual completo.
🔌 Configuración de MCP
Matriz de compatibilidad de clientes
Vigente al 5 de abril de 2026:
| Cliente | Ruta recomendada | Soporte de inicio de sesión en navegador | Respaldo de clave API | Notas |
|---|---|---|---|---|
| Claude Code | MCP remoto alojado primero | verificado en vivo | sí | mejor flujo remoto compatible; stdio local con PLSREADME_API_KEY también funciona bien |
| Cursor | MCP remoto alojado primero | documentado, pero dependiente de la compilación en la práctica | sí | usa encabezados si tu compilación no muestra el aviso de OAuth |
| VS Code | MCP remoto alojado cuando esté disponible | la configuración existe, la implementación varía según la compilación | sí | type: "http" más respaldo de encabezado funciona cuando falta la experiencia de inicio de sesión |
| Windsurf | MCP remoto alojado cuando esté disponible | soporte remoto documentado | sí | usa serverUrl + encabezados cuando la autenticación del navegador aún no esté expuesta |
| Claude Desktop | MCP npm local | sin flujo remoto verificado en navegador aquí | sí | prefiere stdio + PLSREADME_API_KEY |
| HTTP sin procesar / scripts | modo de encabezado remoto alojado | no | sí | envía Authorization: Bearer $PLSREADME_API_KEY directamente |
Inicio de sesión remoto alojado (clientes compatibles)
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"
}
}
}
Notas del ciclo de vida:
- el TTL del token de acceso es de aproximadamente
1 hour - el TTL del token de actualización es de aproximadamente
30 days - reconectar el mismo cliente reemplaza la concesión anterior
- cerrar sesión termina la sesión del sitio web pero no revoca automáticamente una concesión de editor existente
- usa
GET /api/auth/mcp-grantsyDELETE /api/auth/mcp-grants/:grantIdpara auditar o revocar concesiones de editor alojadas
Si tu cliente admite inicio de sesión en el navegador, prefiere esta ruta. Es la configuración más limpia y mantiene los documentos con propietario vinculados automáticamente a tu cuenta del sitio web.
Respaldo de clave API remota alojada
Crea una clave API personal desde https://plsreadme.com/my-links primero, luego usa una de estas:
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}"
}
}
}
}
Usuarios de endpoint remoto sin procesar:
curl -i https://plsreadme.com/mcp \
-H "Authorization: Bearer $PLSREADME_API_KEY"
Respaldo npm local
Claude Code:
claude mcp add --transport stdio \
--env PLSREADME_API_KEY=$PLSREADME_API_KEY \
plsreadme -- npx -y plsreadme-mcp
Cursor:
Agrega a ~/.cursor/mcp.json:
{
"mcpServers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"],
"env": {
"PLSREADME_API_KEY": "${env:PLSREADME_API_KEY}"
}
}
}
}
VS Code:
Agrega a .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:
Agrega a claude_desktop_config.json:
{
"mcpServers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"],
"env": {
"PLSREADME_API_KEY": "<paste-your-personal-api-key>"
}
}
}
}
Windsurf:
Agrega a ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"],
"env": {
"PLSREADME_API_KEY": "${env:PLSREADME_API_KEY}"
}
}
}
}
Notas:
- stdio local ahora espera
PLSREADME_API_KEYpor defecto para que los nuevos documentos tengan propietario - el modo anónimo heredado explícito aún existe con
PLSREADME_ALLOW_ANONYMOUS=1 - crea tu clave desde https://plsreadme.com/my-links
Migración de configuraciones MCP anónimas existentes
Si ya usaste plsreadme-mcp de forma anónima:
- Crea una clave API personal desde
/my-links. - Agrega
PLSREADME_API_KEYa la configuración de tu cliente MCP. - Mantén
PLSREADME_ALLOW_ANONYMOUS=1solo como muleta de compatibilidad temporal para flujos de trabajo antiguos. - Reclama enlaces anónimos antiguos más tarde con
/api/auth/claim-linksi aún tienes suadmin_token.
La regla de migración es simple:
- las creaciones nuevas automatizadas/de editor deben tener propietario por defecto
- el MCP local anónimo ahora es solo heredado y explícito
- la ruta de demostración del sitio web permanece sin configuración incluso mientras la autenticación de editores se vuelve más estricta
add-mcp
npx add-mcp plsreadme-mcp
OpenClaw
clawhub install plsreadme
Docker (para registros de MCP / verificaciones de listados)
Compila y ejecuta el servidor MCP stdio en un contenedor limpio:
docker build -t plsreadme-mcp:local .
docker run --rm -i plsreadme-mcp:local
El servidor en contenedor usa stdio (sin puertos, sin variables de entorno requeridas).
🛠 Herramientas MCP
| Herramienta | Qué hace |
|---|---|
plsreadme_share_file | Comparte un archivo local por ruta → devuelve un enlace compartible. Volver a compartir actualiza el mismo enlace. |
plsreadme_share_text | Comparte markdown o texto plano directamente → devuelve un enlace compartible |
plsreadme_update | Actualiza un documento existente con contenido nuevo (por ID o ruta de archivo) |
plsreadme_delete | Elimina un documento compartido permanentemente (por ID o ruta de archivo) |
plsreadme_list | Lista todos los documentos que has compartido desde este proyecto |
Prompts:
share-document— Flujo guiado para compartir contenido como un enlace legiblerefactor-and-share— Usa tu modelo de IA para refactorizar texto sin procesar en markdown pulido, luego lo comparte
¿Entrada de texto plano? No hay problema — el MCP lo estructura automáticamente en markdown, o puedes usar el prompt refactor-and-share para aprovechar el razonamiento de tu IA para un resultado pulido.
Archivo de registro .plsreadme
El servidor MCP rastrea tus documentos compartidos en un archivo JSON .plsreadme en la raíz de tu proyecto. Esto almacena IDs de documentos, URLs y tokens de administrador necesarios para editar y eliminar.
⚠️ Añade .plsreadme a tu .gitignore — contiene tokens de administrador. La herramienta te avisará si falta.
🏗 Arquitectura
Construido sobre la pila perimetral de Cloudflare para velocidad en todas partes:
┌─────────────┐ ┌──────────────────┐ ┌─────────┐
│ Web / API │────▶│ Cloudflare │────▶│ R2 │
│ MCP Client │ │ Workers (Hono) │ │ (docs) │
└─────────────┘ └──────────────────┘ └─────────┘
│
┌──────┴──────┐
│ D1 │
│ (metadata) │
└─────────────┘
- Hono — Framework web ligero en Workers
- Cloudflare D1 — SQLite en el borde para metadatos, comentarios, análisis
- Cloudflare R2 — Almacenamiento de objetos para documentos markdown
- Durable Objects — Endpoint de servidor MCP con estado
- Workers AI — Respaldo opcional para conversión de texto a markdown
📁 Estructura del Proyecto
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
🔧 Desarrollo
# 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
Notas de migración de la fase de propiedad:
wrangler.jsoncapuntamigrations_diradb/migrations, por lo que el estado de migración es auditable con comandos explícitos de listado/aplicación.- Aplica
db/migrations/004_owner_user_id.sqlen entornos existentes antes de confiar en los filtros de propiedad. - Aplica
db/migrations/007_doc_attribution_telemetry.sqlantes de confiar endoc_create_eventsoraw_view_count. - Las filas heredadas se rellenan intencionalmente como
owner_user_id = NULL(se conserva el comportamiento anónimo/público). - Las rutas de escritura aún ejecutan un paso seguro de garantía de esquema de propiedad (tolerante a columnas duplicadas) para la seguridad de implementación en entornos mixtos.
- Consulta
docs/migrations.mdpara el flujo de trabajo explícito de auditoría/aplicación.
Lanzamiento del paquete MCP
plsreadme-mcp se publica desde packages/mcp al empujar una etiqueta mcp-v* (ver .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
Variables de Entorno
Comienza desde .env.example y establece valores en tu entorno local/dev/prod.
Consejo de Cloudflare: los valores no sensibles pueden vivir en
vars; los valores sensibles deben establecerse conwrangler secret put.
| Variable | Requerido | Descripción |
|---|---|---|
OPENAI_API_KEY | No | Clave de OpenAI para /api/convert texto→markdown |
DISCORD_WEBHOOK_URL | No | Notificaciones de registro en lista de espera |
DISCORD_LINK_WEBHOOK_URL | No | Notificaciones de creación de nuevos enlaces |
RESEND_API_KEY | No | Notificaciones por correo electrónico |
NOTIFICATION_EMAIL | No | Destinatario de correo para notificaciones |
CLERK_PUBLISHABLE_KEY | Para autenticación | Clave publicable de Clerk para la conexión de autenticación del frontend (respaldo social + correo) |
CLERK_JWT_ISSUER | Para autenticación | Emisor JWT de Clerk utilizado por la verificación del worker |
CLERK_JWT_AUDIENCE | Opcional | Reclamación de audiencia esperada para JWT de Clerk |
CLERK_SIGN_IN_URL | Opcional | Sugerencia de URL de inicio de sesión alojada por Clerk (por defecto /sign-in) |
CLERK_SIGN_UP_URL | Opcional | Sugerencia de URL de registro alojada por Clerk (por defecto /sign-up) |
CLERK_SECRET_KEY | Opcional | Reservado para futuras integraciones de Clerk en el lado del servidor |
Si las credenciales OAuth aún no están configuradas, los usuarios pueden hacer clic en Iniciar sesión / Usar correo electrónico en su lugar y completar la autenticación a través del flujo de correo alojado por Clerk de inmediato.
Notas del shell de autenticación del frontend:
/app.htmly/my-linksusanpublic/clerk-auth-shell.js(conexión del SDK de navegador nativo de Clerk).- Las llamadas API del frontend autenticadas deben leer tokens de portador a través de
window.plsreadmeGetAuthToken().
La funcionalidad principal de compartir aún requiere cero configuración. La autenticación de Clerk, la conversión de IA y las notificaciones son opcionales.
Para la lista de verificación completa de configuración de autenticación, consulta docs/auth-clerk.md.
Para implementación + comprobaciones de humo, consulta docs/runbooks/mcp-auth-rollout-checklist.md.
📊 Límites
| Límite | Valor |
|---|---|
| Tamaño máximo de documento | 200 KB |
| Límite de velocidad de subida | 30/hora por clave de actor |
| Límite de velocidad de actualización/restauración | 60/hora por clave de actor |
| Límite de velocidad de conversión de IA | 10/hora por IP |
| Vida útil del enlace | Permanente |
🤝 Contribuciones
¿Ideas de funciones? ¿Informes de errores? Abre un problema.
Se aceptan PRs para correcciones de errores y mejoras.
📄 Licencia
MIT — haz lo que quieras con ello.
Construido por Facundo Lucci