Subwatch

Subwatch는 사용자가 요청했을 때만 공개 Reddit 게시물과 댓글을 읽어 오는 개인용 원격 MCP 서버입니다. Claude 커스텀 커넥터와 Open WebUI가 같은 Streamable HTTP 엔드포인트를 사용할 수 있도록 Cloudflare Workers 위에서 동작합니다.

현재 범위

• 수동 MCP 호출에만 반응
• 예약 실행 없음
• Reddit 콘텐츠 데이터베이스 없음
• 공개 게시물을 조회하며 Reddit의 over_18 표시는 보존하되 서버가 일괄 제외하지 않음
• 작성자 이름은 응답에서 제외
• GitHub OAuth와 숫자 사용자 ID 허용 목록으로 접근 제한
• Reddit 승인 전에는 조작된 테스트 데이터로 동작

MCP 도구

도구	용도
get_recent_posts	정확한 최근 시간 범위에서 top, hot, new, comments 순으로 게시물 조회
search_recent_posts	한 서브레딧 안에서 최근 게시물 키워드 검색
get_post_details	선택한 게시물의 본문과 메타데이터 조회
get_top_comments	선택한 게시물의 상위 댓글 조회
get_server_status	테스트/실제 모드와 저장·예약 실행 여부 확인

사용 예시:

r/LocalLLaMA에서 지난 24시간 동안 에이전트 프레임워크에 관한 인기 게시글을 정리해줘.

호스트 모델은 일반적으로 get_recent_posts 또는 search_recent_posts를 먼저 호출하고, 선별한 게시물에 대해서만 상세 정보와 댓글을 추가로 가져옵니다.

로컬 확인

Node.js 20 이상에서 실행합니다.

npm install
cp .dev.vars.example .dev.vars
npm run typegen
npm run check
npm run dev

실제 비밀값을 .dev.vars나 저장소에 커밋하지 마세요. 기본 REDDIT_MODE는 mock이며 가짜 데이터만 반환합니다.

실제 Reddit API 전환

Reddit의 명시적 승인을 받은 뒤에만 진행합니다.

1. Cloudflare Worker Secrets에 REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET을 저장합니다.
2. wrangler.jsonc의 REDDIT_USER_AGENT에서 u/REPLACE_ME를 실제 Reddit 사용자 이름으로 바꿉니다.
3. REDDIT_MODE를 live로 바꿉니다.
4. npm run typegen && npm run check 후 다시 배포합니다.

현재 실제 API 구현은 앱 전용 OAuth client_credentials와 read 범위를 사용합니다. Reddit이 승인 과정에서 다른 앱 유형이나 인증 흐름을 지정하면 그 안내를 우선하여 어댑터를 수정해야 합니다.

배포

웹과 Android만 사용하는 경우 docs/WEB-DEPLOY.md를 따르세요. 핵심 순서는 다음과 같습니다.

1. OAuth용 Cloudflare KV 네임스페이스 생성
2. KV ID와 GitHub 숫자 사용자 ID를 wrangler.jsonc에 입력
3. GitHub 저장소를 Cloudflare Workers Builds에 연결하여 최초 배포
4. 배포 주소로 GitHub OAuth App 생성
5. Worker Secrets에 GitHub 자격증명과 쿠키 암호화 키 저장
6. https://<worker>.workers.dev/mcp를 Claude 또는 Open WebUI에 연결

Reddit 승인 신청 문안은 docs/REDDIT-APPROVAL.md에 있습니다.

보안 경계

• Reddit·GitHub 비밀값을 소스나 wrangler.jsonc에 넣지 않습니다.
• GitHub 로그인 성공만으로는 충분하지 않습니다. ALLOWED_GITHUB_USER_IDS와 일치해야 MCP 토큰이 발급됩니다.
• OAuth 동의, CSRF, 일회성 state를 짧은 TTL의 KV에 저장합니다.
• Reddit 응답 크기와 MCP 결과 개수를 제한합니다.
• 외부 URL을 임의로 요청하는 도구를 제공하지 않습니다.
• Reddit 콘텐츠와 GitHub 상위 액세스 토큰을 영구 저장하지 않습니다.

자세한 운영 주의사항은 SECURITY.md를 참고하세요.

개발 명령

# wrangler.jsonc의 바인딩 또는 .dev.vars의 secret 이름을 바꿨을 때
npm run typegen

# 커밋된 타입으로 정적 검사와 Workers 런타임 테스트 실행
npm run check

npm run typecheck
npm test
npm run deploy -- --dry-run

GitHub Actions도 push와 pull request마다 npm run check를 실행합니다. worker-configuration.d.ts는 npm run typegen으로 갱신한 뒤 함께 커밋하세요.

라이선스

MIT