RunCoach

Live: runcoach-ruby.vercel.app · MCP 엔드포인트 https://runcoach-ruby.vercel.app/mcp

러너 본인의 훈련 데이터(계산된 훈련 부하, 레이스 시간 예측, 생성된 계획)를 LLM이 호출할 수 있는 도구로 노출하는 MCP 서버입니다.

핵심은 근거(Grounding)입니다. 어떤 어시스턴트에게 "이번 주에 훈련을 줄여야 할까요?"라고 물어보면, 아무 데이터 없이 그럴듯한 코칭 조언을 내놓을 것입니다. RunCoach는 같은 질문을 선수의 실제 기록된 활동 데이터에 기반하여 해결하며, 답변에는 해당 정보가 나온 구체적인 러닝이 포함됩니다:

사용자: 제 훈련 상황은 어떤가요? 하프 마라톤을 뛰면 어떤 기록이 나올까요?

Claude (analyze_training_status 호출 후 predict_race_time 호출): 훈련이 일관되고 부하도 안정적입니다 — 최근 28일 동안 17회의 러닝을 통해 주당 46.8km, 급성-만성 비율 1.00, 3일 이상의 공백이 없습니다. 목표 사이에 있기에는 체력이 유지되고 있지만 향상되지는 않습니다. 이는 적절한 상태이며, 레이스가 다가오면 변화를 고려할 가치가 있습니다.

하프 마라톤 기준: 1:38:49, 대부분 1:36:50에서 1:40:48 사이일 가능성이 높습니다. 이는 5K(21:30, 7월 8일), 10K(44:50, 6월 3일), 하프(1:38:48, 4월 29일) 등 자신의 거리/시간 곡선에 맞춰 산출되었습니다 — 피로 지수는 1.059로 나왔으며, 인구 평균 1.06과 비교할 때 거리가 늘어남에 따라 페이스를 유지하는 능력이 일반적 수준입니다. 하나의 활동은 제외되었습니다: 7월 28일 3km 기록이 해당 거리의 세계 기록보다 빠른 페이스로 기록되어 GPS 오류로 판단되었습니다.

위의 모든 수치는 npm test의 픽스처 선수 데이터를 사용한 실제 출력이며, 예시가 아닙니다 — 정확한 문자열은 test/readme.test.ts에 나타나며, 과학적 계산이 변경되면 README도 그에 맞게 업데이트되지 않으면 테스트가 실패합니다. 모든 도구는 신뢰도와 해당 숫자가 어떻게 도출되었는지에 대한 설명을 반환하며, 서버의 지침은 모델이 이 두 가지를 모두 전달하도록 합니다. 근거 없이 제시된 예측은 추측과 구별할 수 없습니다.

도구

Related MCP server: livetrack-mcp

숫자의 출처

RunCoach는 아무것도 재구현하지 않습니다. 모든 계산은 @runman/core — 픽스처로 테스트된 과학 패키지로, Runman 웹앱도 지원합니다. Claude에게 질문하고 해당 페이지를 로드하는 것은 동일한 코드를 동일한 데이터베이스에 대해 실행하는 것입니다.

해당 패키지는 여기서 git 서브모듈로 제공되며, RunCoach의 테스트는 Runman의 테스트가 사용하는 동일한 픽스처 파일을 가져옵니다 — 따라서 "이 데이터가 무엇을 생성해야 하는가"에 대한 정의가 두 저장소에서 분리되어 표류하지 않고 하나로 통일됩니다.

git clone --recursive https://github.com/varun-gangadharan/runcoach
npm install
npm test          # 31 tests, no database or credentials required

설명이 필요한 설계 결정

도구는 선수 ID를 받지 않습니다. API 키는 정확히 한 명의 선수로 해석되며, 해당 ID가 도구의 컨텍스트가 됩니다. 모델이 선수 ID를 전달할 수 있다면, 활동 제목에 주입된 프롬프트 인젝션 지시가 모델에게 이를 요청할 수 있습니다 — 그리고 여기서 페이로드는 누군가의 개인 건강 데이터입니다. 한 선수의 키로 다른 선수의 데이터를 읽을 수 있다는 근거는 전혀 없습니다. 테스트는 이 사실이 유지됨을 확인합니다.

거절은 유효한 답변입니다. 예측을 뒷받침할 데이터가 없을 때, 도구는 그렇게 말하고 모델이 추정치로 대체하지 않도록 지시합니다. 계획 생성도 마찬가지입니다: 선수에게 최근 훈련이 없거나 레이스가 3주밖에 남지 않았다면, 추정된 기준선에 기반한 계획을 생성하지 않고 이유와 함께 거절합니다. 모델은 기본적으로 빈칸을 채우려고 합니다; 도구 출력은 적극적으로 반발해야 합니다.

출력은 산문(prose)이며, JSON이 아닙니다. 모델은 중첩된 객체를 읽는 것보다 문장을 더 충실히 요약하며, 존재하지 않는 필드를 만들어낼 가능성이 훨씬 적습니다. 정확한 수치는 여전히 나타납니다 — 문장 안에.

각 HTTP 요청은 자체 서버 인스턴스를 생성합니다. 서버리스 환경에서 하나의 인스턴스를 여러 호출에서 공유하면 웜 컨테이너 내에서 두 선수의 세션이 섞일 위험이 있습니다. 이는 여기서 허용할 수 없는 실패 모드입니다.

배포

HTTP 전송은 단일 Vercel 함수입니다. 인증은 Bearer 토큰 — 선수가 Runman 프로필 페이지에서 발급한 API 키로, SHA-256 해시로만 저장됩니다.

vercel env add SUPABASE_URL
vercel env add SUPABASE_SERVICE_ROLE_KEY
vercel deploy --prod

Vercel 진입점(api/mcp.js)은 dist/에서 컴파일된 핸들러를 다시 내보내는 일반 JavaScript이며, src/를 가져오는 TypeScript가 아닙니다. Vercel은 .ts 함수를 제자리에서 컴파일하지만 상대 import 지정자는 그대로 두므로, .ts 지정자가 배포된 번들에 남아 런타임에 제공되지 않은 파일을 찾다가 실패합니다.

배포 후, 실제 MCP 클라이언트로 종단 간 테스트하세요:

node --experimental-strip-types scripts/verify-deployment.ts \
  https://runcoach-ruby.vercel.app/mcp rc_live_...

이는 Claude가 하는 것과 정확히 동일하게 네트워크를 통해 연결됩니다 — 핸드셰이크, 도구 발견, 각 도구 호출 — 그리고 답변이 단순히 형식적으로 잘 구성된 것 이상으로 근거가 있음을 확인합니다.

그런 다음 MCP 클라이언트에 추가하세요:

{
  "mcpServers": {
    "runcoach": {
      "type": "http",
      "url": "https://runcoach-ruby.vercel.app/mcp",
      "headers": { "Authorization": "Bearer rc_live_..." }
    }
  }
}

stdio를 통한 로컬 실행

자신의 데이터를 자신의 기기에서 사용하려면:

{
  "mcpServers": {
    "runcoach": {
      "command": "node",
      "args": ["/absolute/path/to/runcoach/dist/stdio.js"],
      "env": {
        "SUPABASE_URL": "...",
        "SUPABASE_SERVICE_ROLE_KEY": "...",
        "RUNCOACH_API_KEY": "rc_live_..."
      }
    }
  }
}

stdio 서버는 인증할 요청이 없습니다 — 클라이언트의 자식 프로세스로 실행됩니다 — 따라서 선수는 시작 시 고정됩니다. 이는 선수 본인의 기기에서만 적절하며, 배포된 전송이 요청마다 처리하는 이유입니다.

테스트

npm test

세 계층에 걸친 31개의 테스트: Runman의 공유 픽스처 세트(일관된 러너, 심박수 없는 러너, 단일 활동, 빈 이력, GPS 오류 이력, 간헐적 러너, 복귀 러너, 볼륨 급증)에 대한 도구 핸들러, 그리고 실제 MCP 클라이언트를 실제 서버에 연결하여 도구 발견, 스키마 검증, 호출을 수행하는 종단 간 프로토콜 테스트. 세 번째 계층은 이 README에 인용된 예시 수치를 고정합니다.

v1에 포함되지 않은 기능

Garmin 데이터 기반 도구(회복, 수면, HRV) — 상위 Garmin MCP 서버를 프록시하여, 선수가 계정을 연결한 경우에만 사용 가능. 의도적으로 분리되어 있어, Garmin이 없는 선수는 성능 저하를 느끼지 않습니다.

라이선스

MIT.