srs-mcp

에이전트에 무관한(agent-agnostic) MCP 서버로, 간격 반복 학습을 위한 것입니다. Anki GUI도, Xvfb도, AnkiConnect도 필요 없습니다. 에이전트는 직접 가져오세요. 이 서버가 카드 상자와 스케줄러를 제공합니다.

FSRS(Free Spaced Repetition Scheduler, 최신 Anki가 사용하는 것과 같은 알고리즘)를 작은 SQLite 저장소에 감싸서, 에이전트가 카드를 만들고, 복습할 카드를 확인하고, 회상을 기록할 수 있습니다. 완전히 headless로요.

왜 headless Anki가 아닌가?

Anki 데스크톱 앱을 headless로 구동한다는 것은 Qt + 가상 프레임버퍼(Xvfb) + AnkiConnect 애드온을 뜻합니다. 취약하고 버전에 강하게 결합되어 있죠.

anki PyPI 패키지를 쓰면 GUI 없이 실제 .anki2 컬렉션을 구동할 수 있습니다. 휴대폰의 Anki와 연동이 필요하다면요.

하지만 API 뒤에서 간격 반복만 원한다면 Anki 자체가 전혀 필요 없습니다. FSRS는 라이브러리일 뿐이고, 이 서버는 그 주위를 감싼 ~200줄입니다.

Related MCP server: anki-mcp

도구

• add_card(front, back) -> {card_id, due} — 카드를 작성하고 일정을 잡습니다. back은 짧게 유지하세요. 단어나 구절 정도면 됩니다. 몇 초 안에 채점할 수 없는 카드는 플래시카드가 아니라 노트입니다.

• due_cards(q=None, limit=20) -> [{card_id, front, back, deck, due}] — 지금 복습할 카드 목록입니다. 선택적으로 주제로 좁힐 수 있습니다 (q="horace").

• grade_card(card_id, rating) -> {card_id, rating, next_due, reps} — 회상을 기록합니다 (again/hard/good/easy, 또는 1-4).

• edit_card(card_id, front=None, back=None) — 내용을 그 자리에서 수정합니다. 일정은 보존됩니다(중복 생성 대신 오타를 고치거나 긴 답변을 줄이세요).

• suspend_card(card_id) / unsuspend_card(card_id) — 카드를 보류합니다(이력은 유지하고 복습 큐에서 제거) / 복원합니다.

• list_cards(q=None, limit=50) — 복습 예정일과 관계없이 전체를 살펴봅니다.

• delete_card(card_id) — 하나를 삭제합니다(초기화 / 정리).

• stats(deck=None) -> {total, due_now, suspended, reviews, decks}

카드 찾기: 덱이 아니라 검색

카드는 본문을 검색해서 찾습니다 — due_cards(q="horace") — 미리 덱에 분류해 두는 대신입니다. 이제 아무도 deck 필드를 쓰지 않습니다. 주제를 카드 자체에 넣으세요("Horace, Odes 1.11: …"). 그러면 계속 찾을 수 있습니다.

덱은 단일 값, 자유 텍스트, 정확히 일치하는 라벨이었고 덱별 스케줄링도 붙어 있지 않았습니다. 그래서 검색이 못 할 일을 해주지도 못했고, 정확도만 떨어뜨렸습니다. 측정 대상이었던 덱에서 에이전트들은 다섯 가지 구분자 규칙에 걸쳐 Horace를 가리키는 이름 열 개를 만들어 냈습니다. 그 결과 가능한 최선의 deck="Horace"는 Horace 카드 97개 중 20개만 돌려준 반면, q="horac"은 89개를 돌려줍니다 — Talks 아래에 잘못 분류된 카드까지 포함해서요.

due_cards/list_cards/stats의 deck 열과 deck= 필터는 이전 버전에서 라벨이 붙은 카드를 위해 남아 있습니다. plans/002-decks.md를 참조하세요.

복습 루프: due_cards → front로 사용자에게 퀴즈를 내고 → back과 대조 → grade_card. FSRS는 rating을 바탕으로 다음 복습 날짜를 계산합니다.

실행

uv sync
# HTTP (default; for Railway / remote agents)
PORT=8000 uv run srs-mcp
# or stdio (local agent)
MCP_TRANSPORT=stdio uv run srs-mcp

저장소

시작 시 선택되는 두 가지 백엔드:

• Postgres(공유 덱) — SRS_DATABASE_URL(또는 DATABASE_URL)을 Postgres 연결 문자열(예: Neon DB)로 설정하세요. 같은 URL을 가리키는 모든 배포는 하나의 공유 덱을 읽고 씁니다. 따라서 어디서든(로컬, Railway 등) 카드를 추가하고 복습할 수 있습니다. FSRS 카드 ID는 크기가 커서 Postgres에서는 cards.card_id 열이 BIGINT입니다. psycopg 의존성이 필요합니다(이미 선언되어 있음).

• SQLite(폴백) — *DATABASE_URL이 설정되어 있지 않으면 카드는 SRS_DB가 가리키는 SQLite 파일(기본값 ./srs.db)에 저장됩니다. 단일 호스트 / 오프라인용입니다. SQLite-on-Railway 구성에서는 /data에 볼륨을 마운트하고 SRS_DB=/data/srs.db를 유지하면 재배포 후에도 카드 상자가 유지됩니다.

스키마는 동일하며(cards 테이블) 최초 사용 시 자동으로 생성됩니다.