habitica-mcp

자체 호스팅 Habitica 인스턴스를 위한 MCP 서버로, Streamable HTTP로 제공되어 클라이언트별 stdio 하위 프로세스가 아닌 일반 네트워크 서비스로 실행될 수 있습니다.

왜 만들었는가

기존 커뮤니티 서버(iBreaker/habitica-mcp-server)는 https://habitica.com/api/v3를 하드코딩하고, stdio 전용이며, 생성된 지 3일 만에 유지보수가 중단되었습니다. 인그레스 뒤에 있는 자체 호스팅 인스턴스에는 그 어느 것도 맞지 않습니다.

여기서 HABITICA_BASE_URL은 기본값 없이 필수입니다 — 잘못된 인스턴스를 가리키는 것이 단순히 권장되지 않는 수준이 아니라 불가능하게 만듭니다.

Related MCP server: habitca-mcp

도구

구성

엔드포인트: POST/GET/DELETE /mcp, 그리고 GET /healthz.

설계 노트

구조에 영향을 주고 쉽게 알 수 없는 네 가지 결정 사항:

페이지네이션이 아닌 응답 프로젝션. Habitica의 GET /tasks/user는 모든 습관과 데일리에 대해 history: [{date, value}]를 반환합니다 — 계정 수명 동안의 모든 점수 기록 이벤트마다 하나씩이며, 기본적으로 켜져 있습니다. API는 limit/offset을 제공하지 않으므로 해결책은 프로젝션입니다: 이 서버는 항상 history=false를 보내고 각 작업을 고정된 필드 집합으로 추가 프로젝션하여, 상위 스키마 변경이 수백 KB를 모델의 컨텍스트에 조용히 다시 유입시키는 것을 방지합니다. get_user_stats도 같은 이유로 ?userFields=를 사용합니다.

목록 필터는 복수형이고 불규칙합니다. GET /tasks/user?type=는 habits | dailys | todos | rewards | completedTodos를 허용합니다(dailys에 주의). 반면 생성 본문은 단수형 habit | daily | todo | reward를 사용합니다. 도구는 단수형을 노출하고 내부적으로 매핑합니다. 목록 엔드포인트에 단수형을 전달하면 400이 발생합니다.

호스트 검증은 /mcp에만 적용되며 앱 전체에는 적용되지 않습니다. createMcpExpressApp은 이를 전역으로 적용하는데, 이는 kubelet 프로브(httpGet 프로브는 Host: <podIP>를 보내며 pod IP는 절대 허용 목록에 추가할 수 없음)와 블랙박스 모니터링(Host: <svc>.<ns>.svc를 보냄)을 모두 깨뜨립니다. 따라서 /healthz는 가드 밖에 있습니다. 이는 아무것도 노출하지 않으며, DNS 리바인딩 보호는 JSON-RPC 표면에만 의미가 있습니다.

/healthz는 프로세스 활성 상태만 보고합니다 — Habitica 연결 가능성은 절대 보고하지 않습니다. 연결 확인을 넣으면 Habitica 재시작이 여기서 CrashLoopBackOff로 이어지고, 활성 프로브가 대화 상대가 없을 뿐인 완전히 정상적인 프로세스를 계속 종료하게 됩니다. Habitica 장애는 대신 각 도구의 깔끔한 JSON-RPC 오류로 표면화됩니다.

전송

무상태(stateless) Streamable HTTP(sessionIdGenerator: undefined)로, @modelcontextprotocol/server v2 — 현재 안정 메이저 버전 — 위에 구축되었으며, HTTP 전송은 별도의 @modelcontextprotocol/express / @modelcontextprotocol/node 어댑터에 있습니다. 협상된 프로토콜 버전은 2025-11-25(SDK의 LATEST_PROTOCOL_VERSION)입니다. v1.x는 이제 보안 및 버그 수정 전용입니다.

새로운 McpServer + 전송은 요청마다 생성되며, 응답의 close 이벤트에서 정리됩니다. 요청별 생성은 깔끔함이 아니라 필수입니다: SDK v1은 무상태 전송 재사용 시 즉시 예외를 던집니다("Stateless transport cannot be reused across requests"). 재사용은 동시 클라이언트 간 메시지 ID 충돌을 일으키기 때문입니다.

비용은 실재하며 알아둘 가치가 있습니다: 각 요청은 11개의 zod→JSON-Schema 변환을 다시 구축하며, 호출당 약 0.5MB의 가비지를 생성하는 것으로 측정되었습니다. 이는 누수되는 것이 아니라 GC 압력 하에서 회수됩니다(96MB 힙 상한에서 1500회 연속 호출이 ~193MiB에서 안정됨). 그러나 이것이 배포가 유휴 풋프린트가 시사하는 것보다 더 많은 메모리를 요청하는 이유입니다.

GET /mcp는 Allow: POST와 함께 405를 반환합니다. 이는 스펙상 적법하며(서버가 독립 스트림을 거부할 수 있음) MCP 클라이언트가 명시적으로 기대하는 바입니다 — 405를 "여기 서버 스트림 없음"으로 특별 처리하고 중단합니다.

이전 버전은 빈 SSE 스트림을 반환하여 수용하려 했습니다. 이는 무한 재연결 루프를 일으켰습니다: 클라이언트는 응답을 담지 않고 깔끔하게 종료된 스트림을 연결 끊김으로 취급하고 재스케줄하지만, 재시도 카운터는 실패 시에만 증가하므로 성공적인 빈 스트림은 아무것도 재설정하지 않았습니다. 12초 유휴 동안 1 → 4 → 8 → 12 GET으로, 연결된 클라이언트당 하루 약 86,000건의 요청이 어디에도 오류가 표시되지 않은 채 영원히 ~1 req/s로 측정되었습니다. 405를 반환하면 정확히 1로 유지됩니다.

무상태는 장점만 있는 것이 아니라 실질적인 비용이 있습니다: 서버→클라이언트 왕복(sampling, elicitation)과 요청하지 않은 *ListChanged 알림은 작동할 수 없습니다. 클라이언트의 응답은 보류 중인 호출에 대한 기억이 없는 새 서버 인스턴스에 도착하는 새 HTTP 요청으로 오기 때문입니다. 진행 알림은 작동합니다 — 원래 요청의 자체 스트림을 타고 이동합니다. CRUD 도구 표면에는 그 어느 것도 문제가 되지 않지만, 이러한 기능 위에 구축하지 마십시오.

보안

/mcp 엔드포인트는 인증이 없습니다. Habitica 자격 증명은 서버 측에 있으므로 엔드포인트에 도달할 수 있는 사람은 누구나 계정의 전체 작업 목록을 읽고 쓸 수 있습니다. 이는 의도적인 것입니다 — MCP 엔드포인트 앞에 인증 프록시를 두면 MCP 클라이언트가 깨지기 때문입니다 — 그리고 이것이 배포가 사설 네트워크와 단일 레플리카로 제한되는 이유입니다.

API 토큰은 사용자 수준 Habitica 자격 증명입니다(Habitica 자체가 평문으로 저장). 따라서 유출 시 전체 계정이 손상됩니다. 모든 로그 출력은 토큰이 어떤 출력 줄에도 나타나지 않음을 검증하는 테스트와 함께 마스킹 로거를 통과합니다.

개발

npm ci
npm test
npm run lint && npm run typecheck
npm run build && node dist/index.js

라이선스

MIT