plsreadme
Compartilhe arquivos markdown e texto como links web limpos e legíveis. Funciona com Cursor, Claude Desktop, VS Code, Windsurf e qualquer cliente MCP.
Documentação
plsreadme
Cole o markdown. Obtenha um link bonito e compartilhável. Pronto.
Site · Pacote MCP · Solicitar um recurso
O Problema
Você escreveu um README, um PRD, notas de reunião ou uma documentação de API em markdown. Agora você precisa compartilhá-lo com alguém que não tem um renderizador de markdown, não usa GitHub ou apenas precisa de um link limpo que possa abrir no navegador.
plsreadme transforma qualquer markdown em uma página web permanente e lindamente renderizada em uma única etapa. Sem contas. Sem cadastros. Sem fricção.
✨ Recursos
- Compartilhamento instantâneo — Cole markdown ou envie um arquivo, obtenha um link
plsrd.me - Renderização bonita — Tipografia limpa, modo escuro, responsivo para dispositivos móveis
- Comentários inline — Os leitores podem clicar em qualquer parágrafo e deixar feedback
- Modo de revisão (atual vs. linha do tempo) — Documentos com várias versões usam por padrão o feedback do Rascunho atual com acesso em um clique ao histórico completo da Linha do tempo
- Formatação automática por IA — Jogue texto bruto; ele sai como markdown limpo
- Servidor MCP — Compartilhe documentos diretamente do Claude, Cursor, VS Code ou qualquer cliente MCP
- Habilidade OpenClaw — Disponível no ClawHub para fluxos de trabalho de agentes de IA
- Links curtos — Cada documento recebe uma URL
plsrd.me/v/xxxcompacta - Acesso bruto — Baixe o arquivo
.mdoriginal de qualquer link compartilhado - Linha do tempo de versões + restauração segura —
/v/:id/versions+/v/:id/history+ API de restauração com arquivamento primeiro para rollback rápido - Base de autenticação Clerk — Integração de login GitHub/Google + fallback de e-mail hospedado pelo Clerk + utilitários de verificação de autenticação no backend
- Modelo de propriedade (Fase 2) — documentos podem ser vinculados a um usuário Clerk (
owner_user_id) preservando fluxos anônimos - Painel Meus Links (Fase 3) — página
/my-linksautenticada com busca/ordenação/paginação e ações rápidas de copiar/abrir - Reivindicação de links legados (Fase 4) — usuários conectados podem reivindicar links anônimos mais antigos provando o
admin_tokenoriginal - Demonstração do site sem configuração — Sem conta ou chave de API necessária para testar no navegador
🚀 Início Rápido
Web
Acesse plsreadme.com, cole seu markdown, clique em compartilhar.
Caminhos de Autenticação e Estado de Lançamento
Ordem de recomendação:
- Experimente no navegador primeiro — caminho de demonstração mais rápido, sem necessidade de configuração MCP.
- Use MCP remoto hospedado com login no navegador quando o suporte do cliente for verificado.
- Use chave de API / fallback MCP local quando o login interativo não estiver disponível.
Estado de lançamento atual:
| Jornada | Status hoje | Regra de propriedade | Tag de origem |
|---|---|---|---|
| Demonstração anônima no site | Disponível agora via fluxo de demonstração verificado no navegador | owner_user_id = NULL até o usuário salvar/reivindicar o documento depois | web_demo |
| Criação no site com login | Disponível agora | o documento é criado com o usuário Clerk conectado como proprietário | web_signed_in |
| MCP remoto hospedado com login no navegador | Disponível agora em clientes suportados | cria documentos de propriedade do usuário conectado após login no navegador | mcp_remote_login |
| MCP remoto hospedado com chave de API | Disponível agora como fallback de compatibilidade | cria documentos de propriedade do dono da chave de API | mcp_remote_api_key |
| MCP npm local com chave de API | Disponível agora e recomendado para configurações stdio locais | cria documentos de propriedade do dono da chave de API | mcp_local_api_key |
| Fallback anônimo MCP npm local | Ainda disponível apenas com aceitação explícita | permanece anônimo a menos que seja reivindicado/salvo depois | mcp_local_anonymous |
Notas de lançamento do MCP remoto hospedado:
https://plsreadme.com/mcphttps://plsreadme.com/sse
Essas rotas MCP remotas hospedadas estão ativas atrás de login no navegador protegido por OAuth no código, incluindo /authorize, /oauth/token e /oauth/register.
Notas operacionais:
-
D1
doc_create_eventsé a tabela canônica de atribuição de criação em fluxos web, MCP hospedado e MCP local. -
docs.raw_view_countrastreia cada hit de renderização, enquantodocs.view_counté reservado para leituras provavelmente humanas. -
Veja
docs/runbooks/auth-surface-monitoring.mdpara o conjunto de consultas de produção e etapas de resposta. -
tokens de acesso duram cerca de
1 hour -
tokens de atualização duram cerca de
30 days -
reconectar o mesmo cliente substitui a concessão mais antiga
-
sair do site não revoga uma concessão de editor existente por si só
-
este repositório agora está conectado a um binding dedicado do Cloudflare Workers KV chamado
OAUTH_KV
Quando o login no navegador não estiver disponível no seu cliente, crie uma chave de API pessoal em /my-links e use o fallback de cabeçalho remoto hospedado ou o pacote npx -y plsreadme-mcp local.
Modelo de confiança da demonstração do site hoje:
- criações anônimas no site em
/api/create-linkexigem uma concessão de verificação de navegador de curta duração - criações no site com login pulam essa concessão e permanecem sem fricção
- a UI pós-criação agora se ramifica em
Save to my account,Connect your editoreCopy 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_..."
}
Salve o admin_token — você precisará dele para editar ou excluir:
# 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_..."
Linha do tempo de versões + restauração segura
Use o endpoint de linha do tempo para revisar o contexto de revisões durante ciclos de iteração 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" }
]
}
Se uma edição de IA regredir o documento, restaure um snapshot anterior (arquivamento primeiro, não destrutivo):
curl -X POST https://plsreadme.com/v/abc123def456/restore \
-H "Authorization: Bearer sk_..." \
-H "Content-Type: application/json" \
-d '{"version": 4}'
A restauração tem limite de taxa semelhante às atualizações (atualmente 60/hour por chave de ator) para reduzir abuso.
Para documentos de propriedade de um usuário Clerk autenticado, atualizar/excluir/restaurar também exigem a sessão do proprietário (para evitar mutação entre usuários), enquanto documentos anônimos continuam funcionando apenas com admin_token.
Notas de uso do modo de revisão (Rascunho atual primeiro, Linha do tempo sob demanda)
O visualizador de documentos agora expõe controles de revisão de comentários:
- Rascunho atual — mostra apenas comentários vinculados à versão mais recente do documento (padrão quando um documento tem várias versões).
- Linha do tempo — mostra o histórico completo de comentários entre versões.
Você pode buscar os mesmos modos diretamente da 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"
Os links do visualizador persistem o modo na URL para contexto de revisão compartilhável:
https://plsreadme.com/v/abc123def456?view=currenthttps://plsreadme.com/v/abc123def456?view=timeline
Para reivindicar um link anônimo legado na sua conta conectada:
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)
Recomendação atual:
- use MCP remoto hospedado com login no navegador quando seu cliente suportar isso de forma limpa
- use fallback de chave de API pessoal quando a autenticação remota não estiver disponível ou for incômoda nesse cliente
- use o pacote
plsreadme-mcplocal comPLSREADME_API_KEYpara o caminho stdio mais seguro
Conecte seu editor ao plsreadme e compartilhe documentos com linguagem natural:
"Compartilhe este README como um link plsreadme" "Transforme meu PRD em uma página compartilhável" "Transforme estas notas de reunião em um link legível"
Loop de auto-revisão MCP/agente com /versions
Para fluxos de escrita iterativos com IA (rascunho → crítica → revisão), agentes podem consumir /v/:id/versions como fonte da verdade:
- Mantenha a URL canônica legível (
/v/:id) para humanos. - Consulte
/v/:id/versionsentre iterações. - Compare
current_versioncom a última versão revisada. - Se mudou, busque
raw_urlpara a versão mais recente e execute verificações de revisão. - Se a qualidade regredir, opcionalmente acione
/v/:id/restorecom token de administrador + sessão do proprietário.
Isso dá à automação rastreamento determinístico de revisões sem raspar HTML.
Veja docs/ai-iteration-versioning.md para um playbook completo.
🔌 Configuração MCP
Matriz de compatibilidade de clientes
Atualizado em 5 de abril de 2026:
| Cliente | Caminho recomendado | Suporte a login no navegador | Fallback de chave de API | Notas |
|---|---|---|---|---|
| Claude Code | MCP remoto hospedado primeiro | verificado ao vivo | sim | melhor fluxo remoto suportado; stdio local com PLSREADME_API_KEY também funciona bem |
| Cursor | MCP remoto hospedado primeiro | documentado, mas dependente do build na prática | sim | use cabeçalhos se seu build não exibir o prompt OAuth |
| VS Code | MCP remoto hospedado quando disponível | configuração existe, lançamento varia por build | sim | type: "http" mais fallback de cabeçalho funciona quando a UX de login está ausente |
| Windsurf | MCP remoto hospedado quando disponível | suporte remoto documentado | sim | use serverUrl + cabeçalhos quando a autenticação no navegador ainda não estiver exposta |
| Claude Desktop | MCP npm local | sem fluxo remoto verificado no navegador aqui | sim | prefira stdio + PLSREADME_API_KEY |
| HTTP bruto / scripts | modo de cabeçalho remoto hospedado | não | sim | envie Authorization: Bearer $PLSREADME_API_KEY diretamente |
Login Remoto Hospedado (clientes suportados)
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 do ciclo de vida:
- TTL do token de acesso é cerca de
1 hour - TTL do token de atualização é cerca de
30 days - reconectar o mesmo cliente substitui a concessão mais antiga
- sair encerra a sessão do site, mas não revoga automaticamente uma concessão de editor existente
- use
GET /api/auth/mcp-grantseDELETE /api/auth/mcp-grants/:grantIdpara auditar ou revogar concessões de editor hospedadas
Se seu cliente suporta login no navegador, prefira este caminho. É a configuração mais limpa e mantém documentos de propriedade vinculados automaticamente à sua conta do site.
Fallback de chave de API remota hospedada
Crie uma chave de API pessoal em https://plsreadme.com/my-links primeiro, depois use uma destas:
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}"
}
}
}
}
Usuários de endpoint remoto bruto:
curl -i https://plsreadme.com/mcp \
-H "Authorization: Bearer $PLSREADME_API_KEY"
Fallback npm local
Claude Code:
claude mcp add --transport stdio \
--env PLSREADME_API_KEY=$PLSREADME_API_KEY \
plsreadme -- npx -y plsreadme-mcp
Cursor:
Adicione ao ~/.cursor/mcp.json:
{
"mcpServers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"],
"env": {
"PLSREADME_API_KEY": "${env:PLSREADME_API_KEY}"
}
}
}
}
VS Code:
Adicione ao .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:
Adicione ao claude_desktop_config.json:
{
"mcpServers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"],
"env": {
"PLSREADME_API_KEY": "<paste-your-personal-api-key>"
}
}
}
}
Windsurf:
Adicione ao ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"plsreadme": {
"command": "npx",
"args": ["-y", "plsreadme-mcp"],
"env": {
"PLSREADME_API_KEY": "${env:PLSREADME_API_KEY}"
}
}
}
}
Notas:
- stdio local agora espera
PLSREADME_API_KEYpor padrão para que novos documentos sejam de propriedade - modo anônimo legado explícito ainda existe com
PLSREADME_ALLOW_ANONYMOUS=1 - crie sua chave em https://plsreadme.com/my-links
Migrando configurações MCP anônimas existentes
Se você já usou plsreadme-mcp anonimamente:
- Crie uma chave de API pessoal em
/my-links. - Adicione
PLSREADME_API_KEYà configuração do seu cliente MCP. - Mantenha
PLSREADME_ALLOW_ANONYMOUS=1apenas como muleta de compatibilidade temporária para fluxos de trabalho antigos. - Reivindique links anônimos mais antigos depois com
/api/auth/claim-linkse ainda tiver oadmin_tokendeles.
A regra de migração é simples:
- novas criações automatizadas/de editor devem ser de propriedade por padrão
- MCP local anônimo agora é apenas legado e explícito
- o caminho de demonstração do site permanece sem configuração mesmo enquanto a autenticação de editor fica mais rígida
add-mcp
npx add-mcp plsreadme-mcp
OpenClaw
clawhub install plsreadme
Docker (para registros MCP / verificações de listagem)
Construa e execute o servidor MCP stdio em um contêiner limpo:
docker build -t plsreadme-mcp:local .
docker run --rm -i plsreadme-mcp:local
O servidor conteinerizado usa stdio (sem portas, sem variáveis de ambiente necessárias).
🛠 Ferramentas MCP
| Ferramenta | O que faz |
|---|---|
plsreadme_share_file | Compartilha um arquivo local por caminho → retorna link compartilhável. Re-compartilhar atualiza o mesmo link. |
plsreadme_share_text | Compartilha markdown ou texto simples diretamente → retorna link compartilhável |
plsreadme_update | Atualiza um documento existente com novo conteúdo (por ID ou caminho de arquivo) |
plsreadme_delete | Exclui um documento compartilhado permanentemente (por ID ou caminho de arquivo) |
plsreadme_list | Lista todos os documentos que você compartilhou deste projeto |
Prompts:
share-document— Fluxo guiado para compartilhar conteúdo como um link legívelrefactor-and-share— Usa seu modelo de IA para refatorar texto bruto em markdown polido e depois o compartilha
Entrada de texto simples? Sem problema — o MCP estrutura automaticamente em markdown, ou você pode usar o prompt refactor-and-share para aproveitar o raciocínio da sua IA para um resultado polido.
Arquivo de Registro .plsreadme
O servidor MCP rastreia seus documentos compartilhados em um arquivo JSON .plsreadme na raiz do seu projeto. Isso armazena IDs de documentos, URLs e tokens de administrador necessários para editar e excluir.
⚠️ Adicione .plsreadme ao seu .gitignore — ele contém tokens de administrador. A ferramenta avisará se estiver ausente.
🏗 Arquitetura
Construído sobre a stack de edge da Cloudflare para velocidade em qualquer lugar:
┌─────────────┐ ┌──────────────────┐ ┌─────────┐
│ Web / API │────▶│ Cloudflare │────▶│ R2 │
│ MCP Client │ │ Workers (Hono) │ │ (docs) │
└─────────────┘ └──────────────────┘ └─────────┘
│
┌──────┴──────┐
│ D1 │
│ (metadata) │
└─────────────┘
- Hono — Framework web leve no Workers
- Cloudflare D1 — SQLite na edge para metadados, comentários, análises
- Cloudflare R2 — Armazenamento de objetos para documentos markdown
- Durable Objects — Endpoint MCP server com estado
- Workers AI — Fallback opcional para conversão de texto para markdown
📁 Estrutura do Projeto
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
🔧 Desenvolvimento
# 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 sobre a migração da fase de ownership:
wrangler.jsoncapontamigrations_dirparadb/migrations, então o status da migração é auditável com comandos explícitos de list/apply.- Aplique
db/migrations/004_owner_user_id.sqlem ambientes existentes antes de depender dos filtros de ownership. - Aplique
db/migrations/007_doc_attribution_telemetry.sqlantes de depender dedoc_create_eventsouraw_view_count. - Linhas legadas são intencionalmente preenchidas como
owner_user_id = NULL(comportamento anônimo/público preservado). - Rotas de escrita ainda executam uma etapa segura de garantia de schema de ownership (tolerante a colunas duplicadas) para segurança em ambientes mistos.
- Veja
docs/migrations.mdpara o fluxo de trabalho explícito de auditoria/aplicação.
Lançamento do pacote MCP
plsreadme-mcp é publicado a partir de packages/mcp ao enviar uma tag mcp-v* (veja .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
Variáveis de Ambiente
Comece com .env.example e defina os valores no seu ambiente local/dev/prod.
Dica da Cloudflare: valores não sensíveis podem ficar em
vars; valores sensíveis devem ser definidos comwrangler secret put.
| Variável | Obrigatória | Descrição |
|---|---|---|
OPENAI_API_KEY | Não | Chave OpenAI para conversão /api/convert texto→markdown |
DISCORD_WEBHOOK_URL | Não | Notificações de inscrição na lista de espera |
DISCORD_LINK_WEBHOOK_URL | Não | Notificações de criação de novos links |
RESEND_API_KEY | Não | Notificações por e-mail |
NOTIFICATION_EMAIL | Não | Destinatário de e-mail para notificações |
CLERK_PUBLISHABLE_KEY | Para autenticação | Chave pública do Clerk para integração de autenticação no frontend (social + fallback por e-mail) |
CLERK_JWT_ISSUER | Para autenticação | Emissor JWT do Clerk usado na verificação do worker |
CLERK_JWT_AUDIENCE | Opcional | Claim de audience esperado para JWTs do Clerk |
CLERK_SIGN_IN_URL | Opcional | Dica de URL de login hospedada pelo Clerk (padrão /sign-in) |
CLERK_SIGN_UP_URL | Opcional | Dica de URL de cadastro hospedada pelo Clerk (padrão /sign-up) |
CLERK_SECRET_KEY | Opcional | Reservado para futuras integrações do Clerk no servidor |
Se as credenciais OAuth ainda não estiverem configuradas, os usuários ainda podem clicar em Entrar / Usar e-mail e concluir a autenticação pelo fluxo de e-mail hospedado pelo Clerk imediatamente.
Notas do shell de autenticação do frontend:
/app.htmle/my-linksusampublic/clerk-auth-shell.js(integração do SDK de navegador nativo do Clerk).- Chamadas autenticadas da API no frontend devem ler tokens de portador via
window.plsreadmeGetAuthToken().
A funcionalidade principal de compartilhamento ainda exige zero configuração. Autenticação do Clerk, conversão por IA e notificações são opcionais.
Para a lista de verificação completa de configuração de autenticação, veja docs/auth-clerk.md.
Para verificações de rollout + smoke tests, veja docs/runbooks/mcp-auth-rollout-checklist.md.
📊 Limites
| Limite | Valor |
|---|---|
| Tamanho máximo do documento | 200 KB |
| Limite de upload | 30/hora por chave de ator |
| Limite de atualização/restauração | 60/hora por chave de ator |
| Limite de conversão por IA | 10/hora por IP |
| Vida útil do link | Permanente |
🤝 Contribuindo
Ideias de funcionalidades? Relatos de bugs? Abra uma issue.
PRs são bem-vindos para correções de bugs e melhorias.
📄 Licença
MIT — faça o que quiser com ele.
Construído por Facundo Lucci