srs-mcp — 간격 반복, MCP 서버로 구현

MCP를 지원하는 모든 에이전트(Claude Code, Claude Desktop 또는 기타 MCP 호스트)에게 매 세션마다 마크다운 표에서 "오늘 할 것"을 수동으로 다시 유도하는 대신, 실제로 올바르게 스케줄링된 간격 반복 기억을 제공합니다. Anki/SuperMemo의 기반 알고리즘인 SM-2를 네 개의 호출 가능한 도구로 구현하며, 로컬 SQLite 파일을 백엔드로 사용합니다. 계정 없음, 네트워크 호출 없음, 텔레메트리 없음 — 모든 것이 사용자 머신에서 실행됩니다.

상태: 프로토타입, 아직 어디에도 게시되지 않음. 로컬에서 빌드 및 검증됨(아래 "검증 방법" 참조); 아직 이 프로젝트 외부에서 설치된 적 없음. 버전 0.2.0은 사전 릴리스로 취급하십시오.

왜 필요한가

마크다운 체크리스트와 어휘 표는 사람들(및 이를 돕는 에이전트)이 복습할 내용을 추적하는 일반적인 방법이지만, 실제 일정을 계산해 주는 것은 없습니다 — "오늘 할 것"은 결국 매번 눈으로 다시 읽는 추측에 불과합니다. srs-mcp는 빠진 조각입니다: 도구로 노출된 작고 실제적인 스케줄링 알고리즘으로, 에이전트가 SM-2를 프롬프트에 다시 구현하지 않고도 플래시카드, 면접 질문, 어휘, 온보딩 퀴즈 등 무엇이든 복습 상태를 추적할 수 있게 합니다.

네 가지 핵심 도구 (무료, 무제한, 영구)

Pro 이용하기

두 개의 추가 도구는 Pro 라이선스 뒤에 게이트되어 있습니다 — 이것이 srs-mcp가 구독이나 호스팅 백엔드 대신 사용하는 무료/유료 분할입니다:

라이선싱 작동 방식(구체적으로): srs-mcp는 유지관리자의 머신을 벗어나지 않는 Ed25519 개인 키로 라이선스 키에 서명합니다; 이 저장소에는 일치하는 공개 키(license.py)만 포함되어 있으며, 이 키는 서명을 검증할 수 있지만 위조할 수는 없습니다. 키를 구매하여 SRS_LICENSE_KEY (환경 변수)로 설정하거나 ~/.srs-mcp/license.key에 저장하면 Pro 도구가 잠금 해제됩니다 — 계정 없음, 전화-홈 확인 없음, 오프라인에서 작동. 전체 메커니즘과 명시된 한계는 license.py를 참조하십시오(요약: 우연한 복사를 억제하는 것이지 DRM이 아닙니다 — 오픈소스 Python 파일의 자체 로컬 복사본에서 검사를 패치하는 것을 막을 수 있는 것은 없습니다; 이 트레이드오프에 대한 솔직한 설명은 모듈 docstring을 참조하십시오).

아직 실제 구매 링크는 없습니다. 이 섹션은 작동 중인 스토어가 아닌, 빌드되고 테스트된 메커니즘(test_license_gate.py 참조)을 설명합니다. 구매 흐름이 생기면 여기에 추가됩니다.

설치

Python 3.11+ 필요.

git clone <repo-url>   # not yet public — see status note above
cd srs-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/srs-mcp       # runs the server on stdio

Claude Code 플러그인으로 사용하려면 Claude Code가 이 디렉토리를 가리키게 하십시오(또는 게시된 후에는 마켓플레이스 목록을) — .claude-plugin/plugin.json과 .mcp.json이 이미 설정되어 있습니다; 서버는 SRS_DB_PATH를 읽으므로 플러그인 설치 데이터가 업데이트 후에도 유지됩니다(Claude Code에서는 ${CLAUDE_PLUGIN_DATA}/srs.db, 직접/수동 실행에서는 동일 위치의 srs.db).

검증 방법

단순히 "import가 된다"는 수준이 아니라 — 실제 MCP 프로토콜을 통해 실제로 실행되었습니다:

• test_client.py는 server.py를 하위 프로세스로 실행하고(실제 MCP 호스트가 하는 것과 동일한 방식), 전체 add/list/grade/list 세션을 구동한 후 테스트 하네스 외부에서 결과 SQLite 행을 독립적으로 재검증합니다.

• test_license_gate.py는 서버를 세 가지 방식(라이선스 없음, 유효한 라이선스, 변조된 라이선스)으로 실행하고 export_items / get_forecast가 경우 1과 3에서 거부하고 경우 2에서 실제 데이터를 반환하는지 확인합니다 — 라이선스 검사가 실제 게이트이지 no-op이 아님을 증명합니다.

• ingest_chinese_vocab.py와 ingest_leetcode.py는 이 프로젝트의 마크다운 트래커에서 실제 개인 데이터(중국어 어휘 114개, 완료된 LeetCode 문제 16개)를 직접 SQLite 쓰기가 아닌 실제 add_item MCP 호출을 통해 시드하는 작동하는 멱등성 수집 스크립트입니다.

"출시 준비 완료"까지의 솔직한 격차 — 과장하지 않음

1. 공개 저장소 없음. 모든 실제 배포 경로(Claude Code의 커뮤니티 플러그인 마켓플레이스, GitHub 릴리스, MCP 디렉토리 목록)는 공개 git URL에서 접근 가능해야 합니다. 이 프로젝트는 로컬 전용입니다. 이를 만드는 것(GitHub 저장소, 아마도 계정)은 명시적인 승인 없이는 이 프로젝트의 현재 자율성 범위 밖입니다 — 위의 모든 것은 승인이 주어지면 빌드 작업이 아닌 복사-및-푸시 작업이 되도록 준비되어 있습니다.

2. claude plugin validate로 자체 검증 불가. 이 개발 환경에는 claude CLI나 Node/npx가 없습니다. 플러그인 매니페스트는 Anthropic 문서를 주의 깊게 읽고 그들의 자체 프로덕션 marketplace.json을 교차 참조하여 확인할 수 있는 한 스키마를 준수하지만, 기계 검증된 것은 아닙니다.

3. 실제 구매 흐름 없음. 라이선스 메커니즘은 실제이며 테스트되었 습니다; 이를 실제 판매로 전환하려면 아직 존재하지 않는 스토어프런트 (Ko-fi, Gumroad 등)가 필요합니다 — 이는 계정 생성 단계로, 승인 없이는 이 프로젝트의 자율성 범위 밖입니다.

4. 라이선스 집행은 무결성 기반이지 변조 방지가 아닙니다. 읽을 수 있는 Python을 배포하는 특성상 설계상 그리고 본질적으로 — 위의 "Pro 이용하기" 섹션과 license.py의 docstring을 참조하십시오.

5. 인증/멀티테넌트 스토리 없음. 단일 로컬 SQLite 파일, 단일 사용자. 현재의 "사용자 머신에서 실행" 모델에는 적합합니다; 호스팅/ 팀 제품이 되려면 실제 설계 작업이 필요합니다.

6. 외부 검증 제로. 이 프로젝트 외부에서 설치하거나 사용한 사람이 없습니다. 위의 모든 주장은 "빌드되고 테스트된 대로 작동한다"는 것이지 "사람들이 원하는 것"이 아닙니다.

라이선스

MIT — LICENSE 참조. (Pro 티어의 라이선스 키 메커니즘은 코드 자체의 MIT 라이선스와 별개입니다 — 위의 "Pro 이용하기" 참조.)