Readeck MCP

Readeck 라이브러리를 AI 에이전트용 읽기/쓰기 지식 베이스로 바꿔주는 MCP 서버입니다. 에이전트가 생성한 HTML을 Readeck에 바로 저장하고(LLM이 자동 태깅), 나중에 해당 문서를 다시 검색하고 읽을 수 있습니다. FastMCP로 제작되어, 동일한 코드가 로컬 stdio 서버 또는 리버스 프록시 뒤의 원격 HTTP 서버로 실행됩니다.

기존 Readeck MCP(읽기 전용 리딩 어시스턴트)와 달리, 이 서버는 에이전트가 생성한 HTML을 수집하고 고정된 분류 체계에서 LLM으로 자동 라벨링합니다.

도구

readeck_save는 원시 HTML html 필드가 포함된 Readeck의 JSON 생성 API를 사용합니다(base64/data-URI는 작동하지 않음). WAF(예: Cloudflare 오류 1010)가 차단하지 않도록 브라우저 User-Agent를 전송하고, 새 북마크 id, word_count, reading_url을 반환하기 위해 잠시 폴링합니다.

Related MCP server: Doc Monitor MCP

자동 라벨링

labels 없이 readeck_save를 호출하면 LLM이 문서를 분류합니다. 설계상 주입에 강합니다: 모델은 고정된 분류 체계(LABEL_TAXONOMY)에서만 선택할 수 있고, 결과는 서버 측에서 해당 목록과 교차 검증되므로 어휘 외 라벨은 불가능합니다. 출처 라벨(ORIGIN_LABEL, 기본값 propio)은 LLM이 아닌 코드로 항상 추가됩니다.

공급자 중립적(OpenAI 호환 또는 Anthropic). Groq 같은 무료 티어에서도 작동합니다. gpt-oss 같은 추론 모델의 경우 넉넉한 LLM_MAX_TOKENS를 설정하면 서버가 자동으로 reasoning_effort: low를 전송합니다.

안전장치

• 실패 시 폐쇄되는 HTTP 인증: HTTP 전송에서 모든 도구 호출은 Authorization: Bearer $MCP_AUTH_TOKEN(상수 시간 비교)이 필요합니다.

• 입력 검증: HTML 크기 제한, 비-HTML 거부, URL 스킴 허용 목록, 라벨 정리 + 제한.

• 프로세스당 토큰 버킷 속도 제한.

• LLM 호출은 429/5xx에서 백오프로 재시도하고 우아하게 저하됩니다(라벨링은 최선 노력이며, 실패해도 저장을 차단하지 않음).

구성(환경)

로컬(stdio)

READECK_TOKEN=... uv run --script server.py --selftest   # smoke test

MCP 클라이언트(mcpServers)에 등록합니다. 예:

{
  "mcpServers": {
    "readeck": {
      "command": "uv",
      "args": ["run", "--script", "/path/to/readeck-mcp/server.py"],
      "env": { "READECK_URL": "https://readeck.example.com", "READECK_TOKEN": "..." }
    }
  }
}

원격(HTTP / Docker)

READECK_MCP_TRANSPORT=http로 실행합니다(Dockerfile 참조). 리버스 프록시/터널 뒤에 예: https://mcp-readeck.example.com에 배치합니다. Readeck과 함께 배치할 때는 READECK_URL=http://readeck:8000로 설정하여 공개 왕복을 건너뜁니다. 클라이언트를 엔드포인트로 지정합니다:

{
  "mcpServers": {
    "readeck": {
      "type": "http",
      "url": "https://mcp-readeck.example.com/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

참고: 엔드포인트 경로를 후행 슬래시 없이 사용하세요(/mcp/가 아닌 /mcp). 일부 프록시는 후행 슬래시 리디렉트를 307로 바꿔 스트리밍 가능한 HTTP 클라이언트를 깨뜨립니다.

엔드포인트를 노출하기 전에 항상 강력한 MCP_AUTH_TOKEN을 설정하세요. 토큰은 라이브러리에 대한 쓰기 액세스를 부여합니다.

라이선스

MIT