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

plsreadme

Cole o markdown. Obtenha um link bonito e compartilhável. Pronto.

Site · Pacote MCP · Solicitar um recurso

npm version Cloudflare Workers MCP compatible License


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/xxx compacta
  • Acesso bruto — Baixe o arquivo .md original 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-links autenticada 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_token original
  • 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:

  1. Experimente no navegador primeiro — caminho de demonstração mais rápido, sem necessidade de configuração MCP.
  2. Use MCP remoto hospedado com login no navegador quando o suporte do cliente for verificado.
  3. Use chave de API / fallback MCP local quando o login interativo não estiver disponível.

Estado de lançamento atual:

JornadaStatus hojeRegra de propriedadeTag de origem
Demonstração anônima no siteDisponível agora via fluxo de demonstração verificado no navegadorowner_user_id = NULL até o usuário salvar/reivindicar o documento depoisweb_demo
Criação no site com loginDisponível agorao documento é criado com o usuário Clerk conectado como proprietárioweb_signed_in
MCP remoto hospedado com login no navegadorDisponível agora em clientes suportadoscria documentos de propriedade do usuário conectado após login no navegadormcp_remote_login
MCP remoto hospedado com chave de APIDisponível agora como fallback de compatibilidadecria documentos de propriedade do dono da chave de APImcp_remote_api_key
MCP npm local com chave de APIDisponível agora e recomendado para configurações stdio locaiscria documentos de propriedade do dono da chave de APImcp_local_api_key
Fallback anônimo MCP npm localAinda disponível apenas com aceitação explícitapermanece anônimo a menos que seja reivindicado/salvo depoismcp_local_anonymous

Notas de lançamento do MCP remoto hospedado:

  • https://plsreadme.com/mcp
  • https://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_count rastreia cada hit de renderização, enquanto docs.view_count é reservado para leituras provavelmente humanas.

  • Veja docs/runbooks/auth-surface-monitoring.md para 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-link exigem 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 editor e 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_..."
}

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=current
  • https://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-mcp local com PLSREADME_API_KEY para 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:

  1. Mantenha a URL canônica legível (/v/:id) para humanos.
  2. Consulte /v/:id/versions entre iterações.
  3. Compare current_version com a última versão revisada.
  4. Se mudou, busque raw_url para a versão mais recente e execute verificações de revisão.
  5. Se a qualidade regredir, opcionalmente acione /v/:id/restore com 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:

ClienteCaminho recomendadoSuporte a login no navegadorFallback de chave de APINotas
Claude CodeMCP remoto hospedado primeiroverificado ao vivosimmelhor fluxo remoto suportado; stdio local com PLSREADME_API_KEY também funciona bem
CursorMCP remoto hospedado primeirodocumentado, mas dependente do build na práticasimuse cabeçalhos se seu build não exibir o prompt OAuth
VS CodeMCP remoto hospedado quando disponívelconfiguração existe, lançamento varia por buildsimtype: "http" mais fallback de cabeçalho funciona quando a UX de login está ausente
WindsurfMCP remoto hospedado quando disponívelsuporte remoto documentadosimuse serverUrl + cabeçalhos quando a autenticação no navegador ainda não estiver exposta
Claude DesktopMCP npm localsem fluxo remoto verificado no navegador aquisimprefira stdio + PLSREADME_API_KEY
HTTP bruto / scriptsmodo de cabeçalho remoto hospedadonãosimenvie 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-grants e DELETE /api/auth/mcp-grants/:grantId para 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_KEY por 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:

  1. Crie uma chave de API pessoal em /my-links.
  2. Adicione PLSREADME_API_KEY à configuração do seu cliente MCP.
  3. Mantenha PLSREADME_ALLOW_ANONYMOUS=1 apenas como muleta de compatibilidade temporária para fluxos de trabalho antigos.
  4. Reivindique links anônimos mais antigos depois com /api/auth/claim-link se ainda tiver o admin_token deles.

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

FerramentaO que faz
plsreadme_share_fileCompartilha um arquivo local por caminho → retorna link compartilhável. Re-compartilhar atualiza o mesmo link.
plsreadme_share_textCompartilha markdown ou texto simples diretamente → retorna link compartilhável
plsreadme_updateAtualiza um documento existente com novo conteúdo (por ID ou caminho de arquivo)
plsreadme_deleteExclui um documento compartilhado permanentemente (por ID ou caminho de arquivo)
plsreadme_listLista todos os documentos que você compartilhou deste projeto

Prompts:

  • share-document — Fluxo guiado para compartilhar conteúdo como um link legível
  • refactor-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.jsonc aponta migrations_dir para db/migrations, então o status da migração é auditável com comandos explícitos de list/apply.
  • Aplique db/migrations/004_owner_user_id.sql em ambientes existentes antes de depender dos filtros de ownership.
  • Aplique db/migrations/007_doc_attribution_telemetry.sql antes de depender de doc_create_events ou raw_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.md para 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 com wrangler secret put.

VariávelObrigatóriaDescrição
OPENAI_API_KEYNãoChave OpenAI para conversão /api/convert texto→markdown
DISCORD_WEBHOOK_URLNãoNotificações de inscrição na lista de espera
DISCORD_LINK_WEBHOOK_URLNãoNotificações de criação de novos links
RESEND_API_KEYNãoNotificações por e-mail
NOTIFICATION_EMAILNãoDestinatário de e-mail para notificações
CLERK_PUBLISHABLE_KEYPara autenticaçãoChave pública do Clerk para integração de autenticação no frontend (social + fallback por e-mail)
CLERK_JWT_ISSUERPara autenticaçãoEmissor JWT do Clerk usado na verificação do worker
CLERK_JWT_AUDIENCEOpcionalClaim de audience esperado para JWTs do Clerk
CLERK_SIGN_IN_URLOpcionalDica de URL de login hospedada pelo Clerk (padrão /sign-in)
CLERK_SIGN_UP_URLOpcionalDica de URL de cadastro hospedada pelo Clerk (padrão /sign-up)
CLERK_SECRET_KEYOpcionalReservado 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.html e /my-links usam public/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

LimiteValor
Tamanho máximo do documento200 KB
Limite de upload30/hora por chave de ator
Limite de atualização/restauração60/hora por chave de ator
Limite de conversão por IA10/hora por IP
Vida útil do linkPermanente

🤝 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