plsreadme

문제점

마크다운으로 README, PRD, 회의록 또는 API 문서를 작성했습니다. 이제 마크다운 렌더러가 없거나, GitHub를 사용하지 않거나, 브라우저에서 열 수 있는 깔끔한 링크가 필요한 사람과 공유해야 합니다.

plsreadme는 어떤 마크다운이든 한 번의 단계로 영구적이고 아름답게 렌더링된 웹 페이지로 변환합니다. 계정이나 가입이 필요 없으며, 번거로움도 없습니다.

✨ 주요 기능

• 즉시 공유 — 마크다운을 붙여넣거나 파일을 업로드하면 plsrd.me 링크를 받을 수 있습니다.

• 아름다운 렌더링 — 깔끔한 타이포그래피, 다크 모드, 모바일 반응형 지원

• 인라인 댓글 — 독자가 단락을 클릭하여 피드백을 남길 수 있습니다.

• 검토 모드 (현재 vs 타임라인) — 다중 버전 문서는 기본적으로 현재 초안 피드백을 보여주며, 클릭 한 번으로 전체 타임라인 기록에 접근할 수 있습니다.

• AI 자동 서식 지정 — 원시 텍스트를 입력하면 깔끔한 마크다운으로 변환됩니다.

• MCP 서버 — Claude, Cursor, VS Code 또는 모든 MCP 클라이언트에서 직접 문서를 공유하세요.

• OpenClaw 스킬 — AI 에이전트 워크플로우를 위해 ClawHub에서 사용할 수 있습니다.

• 단축 링크 — 모든 문서는 간결한 plsrd.me/v/xxx URL을 가집니다.

• 원본 접근 — 공유된 링크에서 원본 .md 파일을 다운로드할 수 있습니다.

• 버전 타임라인 + 안전한 복원 — /v/:id/versions + /v/:id/history + 빠른 롤백을 위한 아카이브 우선 복원 API

• Clerk 인증 기반 — GitHub/Google 로그인 연동 + Clerk 호스팅 이메일 폴백 + 백엔드 인증 확인 유틸리티

• 소유권 모델 (2단계) — 익명 흐름을 유지하면서 문서를 Clerk 사용자(owner_user_id)에게 연결할 수 있습니다.

• 내 링크 대시보드 (3단계) — 검색/정렬/페이지 매김 및 빠른 복사/열기 작업이 가능한 인증된 /my-links 페이지

• 레거시 링크 소유권 주장 (4단계) — 로그인한 사용자는 원본 admin_token을 증명하여 이전 익명 링크의 소유권을 주장할 수 있습니다.

• 제로 구성 웹사이트 데모 — 브라우저에서 사용해 보기 위해 계정이나 API 키가 필요하지 않습니다.

🚀 빠른 시작

웹

plsreadme.com에 접속하여 마크다운을 붙여넣고 공유를 클릭하세요.

인증 경로 및 출시 상태

권장 순서:

1. 브라우저에서 먼저 시도 — 가장 빠른 데모 경로, MCP 설정 불필요.

2. 클라이언트 지원이 확인되면 브라우저 로그인이 포함된 호스팅 원격 MCP 사용.

3. 대화형 로그인을 사용할 수 없는 경우 API 키 / 로컬 MCP 폴백 사용.

현재 출시 상태:

호스팅 원격 MCP 출시 참고 사항:

• https://plsreadme.com/mcp

• https://plsreadme.com/sse

해당 호스팅 원격 MCP 경로는 /authorize, /oauth/token, /oauth/register를 포함하여 코드 내 OAuth 보호 브라우저 로그인 뒤에서 라이브 상태입니다.

운영 참고 사항:

• D1 doc_create_events는 웹, 호스팅 MCP 및 로컬 MCP 흐름 전반에 걸친 표준 생성 속성 테이블입니다.

• docs.raw_view_count는 모든 렌더링 히트를 추적하며, docs.view_count는 사람이 읽은 것으로 추정되는 조회수 전용입니다.

• 프로덕션 쿼리 세트 및 대응 단계는 docs/runbooks/auth-surface-monitoring.md를 참조하세요.

• 액세스 토큰은 약 1시간 동안 지속됩니다.

• 리프레시 토큰은 약 30일 동안 지속됩니다.

• 동일한 클라이언트를 다시 연결하면 이전 권한이 대체됩니다.

• 웹사이트에서 로그아웃해도 기존 편집자 권한이 자동으로 취소되지는 않습니다.

• 이 저장소는 이제 OAUTH_KV라는 전용 Cloudflare Workers KV 바인딩에 연결되어 있습니다.

클라이언트에서 브라우저 로그인을 사용할 수 없는 경우, /my-links에서 개인 API 키를 생성하고 호스팅 원격 헤더 폴백 또는 로컬 npx -y plsreadme-mcp 패키지를 사용하세요.

현재 웹사이트 데모 신뢰 모델:

• /api/create-link에서 생성되는 익명 웹사이트는 단기 브라우저 검증 권한이 필요합니다.

• 로그인한 웹사이트 생성은 해당 권한을 건너뛰며 마찰이 적습니다.

• 생성 후 UI는 이제 내 계정에 저장, 편집기 연결, 링크 복사로 분기됩니다.

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

admin_token을 저장하세요. 편집하거나 삭제할 때 필요합니다:

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

버전 타임라인 + 안전한 복원

AI 반복 주기 동안 수정 컨텍스트를 검토하려면 타임라인 엔드포인트를 사용하세요:

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

AI 편집으로 인해 문서가 퇴보하면 이전 스냅샷을 복원하세요 (아카이브 우선, 비파괴적):

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

복원은 남용을 줄이기 위해 업데이트와 유사하게 속도 제한이 적용됩니다 (현재 액터 키당 60회/시간).

인증된 Clerk 사용자가 소유한 문서의 경우, 업데이트/삭제/복원 시에도 해당 소유자 세션이 필요합니다(사용자 간 변조 방지). 반면 익명 문서는 admin_token만으로 계속 작동합니다.

검토 모드 사용 참고 사항 (현재 초안 우선, 타임라인 요청 시)

문서 뷰어는 이제 댓글 검토 제어 기능을 노출합니다:

• 현재 초안 — 최신 문서 버전에 연결된 댓글만 표시합니다 (문서에 여러 버전이 있을 때 기본값).

• 타임라인 — 전체 버전 간 댓글 기록을 표시합니다.

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"

뷰어 링크는 공유 가능한 검토 컨텍스트를 위해 URL에 모드를 유지합니다:

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

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

레거시 익명 링크를 로그인한 계정으로 가져오려면:

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 편집기)

현재 권장 사항:

• 클라이언트가 깔끔하게 지원하는 경우 브라우저 로그인이 포함된 호스팅 원격 MCP를 사용하세요.

• 해당 클라이언트에서 원격 인증을 사용할 수 없거나 불편한 경우 개인 API 키 폴백을 사용하세요.

• 가장 안전한 stdio 경로를 위해 PLSREADME_API_KEY와 함께 로컬 plsreadme-mcp 패키지를 사용하세요.

편집기를 plsreadme에 연결하고 자연어로 문서를 공유하세요:

*"이 README를 plsreadme 링크로 공유해줘" *"내 PRD를 공유 가능한 페이지로 바꿔줘" "이 회의록을 읽기 쉬운 링크로 만들어줘"

/versions를 사용한 MCP/에이전트 자동 검토 루프

반복적인 AI 작성 흐름(초안 → 비평 → 수정)의 경우, 에이전트는 /v/:id/versions를 진실의 원천으로 사용할 수 있습니다:

1. 사람을 위해 표준 읽기 가능한 URL(/v/:id)을 유지하세요.

2. 반복 주기 사이에 /v/:id/versions를 폴링하세요.

3. current_version을 마지막으로 검토된 버전과 비교하세요.

4. 변경된 경우 최신 버전에 대한 raw_url을 가져와 검토 확인을 실행하세요.

5. 품질이 퇴보하면 관리자 토큰 + 소유자 세션으로 /v/:id/restore를 선택적으로 트리거하세요.

이렇게 하면 HTML을 스크래핑하지 않고도 자동화된 결정론적 수정 추적이 가능합니다.

전체 플레이북은 docs/ai-iteration-versioning.md를 참조하세요.

🔌 MCP 설정

클라이언트 호환성 매트릭스

2026년 4월 5일 기준:

호스팅 원격 로그인 (지원되는 클라이언트)

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

수명 주기 참고 사항:

• 액세스 토큰 TTL은 약 1시간입니다.

• 리프레시 토큰 TTL은 약 30일입니다.

• 동일한 클라이언트를 다시 연결하면 이전 권한이 대체됩니다.

• 로그아웃하면 웹사이트 세션은 종료되지만 기존 편집자 권한이 자동으로 취소되지는 않습니다.

• 호스팅 편집자 권한을 감사하거나 취소하려면 GET /api/auth/mcp-grants 및 DELETE /api/auth/mcp-grants/:grantId를 사용하세요.

클라이언트가 브라우저 로그인을 지원하는 경우 이 경로를 선호하세요. 가장 깔끔한 설정이며 소유한 문서를 웹사이트 계정에 자동으로 연결된 상태로 유지합니다.

호스팅 원격 API 키 폴백

먼저 https://plsreadme.com/my-links에서 개인 API 키를 생성한 다음 다음 중 하나를 사용하세요:

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

원시 원격 엔드포인트 사용자:

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

로컬 npm 폴백

Claude Code:

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

Cursor: ~/.cursor/mcp.json에 추가:

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

VS Code: .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: claude_desktop_config.json에 추가:

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

Windsurf: ~/.codeium/windsurf/mcp_config.json에 추가:

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

참고 사항:

• 로컬 stdio는 이제 기본적으로 PLSREADME_API_KEY를 기대하므로 새 문서는 소유권이 부여됩니다.

• PLSREADME_ALLOW_ANONYMOUS=1을 사용한 명시적 레거시 익명 모드는 여전히 존재합니다.

• https://plsreadme.com/my-links에서 키를 생성하세요.

기존 익명 MCP 설정 마이그레이션

이미 plsreadme-mcp를 익명으로 사용한 경우:

1. /my-links에서 개인 API 키를 생성하세요.

2. MCP 클라이언트 구성에 PLSREADME_API_KEY를 추가하세요.

3. 이전 워크플로우에 대한 일시적인 호환성 수단으로만 PLSREADME_ALLOW_ANONYMOUS=1을 유지하세요.

4. 여전히 admin_token이 있는 경우 나중에 /api/auth/claim-link로 이전 익명 링크의