Long Run Hybrid Coach

繁體中文 · English · 简体中文

Long Run Hybrid Coach는 비공식적이고, Intervals 우선이며, 기기 독립적인 개인 맞춤형 하이브리드 트레이닝 코치입니다. 동일한 28일 방향성과 이번 주 러닝＋근력 운동 계획을 유지하고, 신뢰할 수 있는 실제 완료 evidence를 읽어 지속적으로 복기하며, 사용자가 확인한 후에 계획을 Intervals.icu 캘린더로 보낼 수 있습니다.

Garmin은 사용 전제 조건이 아닙니다. Garmin은 현재 실기 dogfood를 거친 첫 번째 다운스트림 기기 경로입니다. Apple Watch, COROS, Polar, Suunto, Wahoo, 기타 앱/시계, 심지어 시계가 없는 경우에도 동일한 Coach를 사용할 수 있습니다. 차이는 얼마나 많은 신뢰할 수 있는 evidence가 훈련 루프에 들어갈 수 있는지, 그리고 Intervals 이후의 기기 동기화 경로가 검증되었는지 여부입니다.

일반 사용자는 Hosted MCP를 우선 선택하세요: https://mcp.paceandstaystrong.com/mcp. Intervals.icu 계정이 필요하지만, 직접 Intervals OAuth App을 만들 필요도 없고 gateway를 직접 운영할 필요도 없습니다.

Quick Start: Hosted MCP

사용 전에 무엇이 필요한가요?

1. Intervals.icu 계정 하나.

2. 원격 MCP에 연결할 수 있고, 이 제품이 필요로 하는 액션을 제공할 수 있는 AI client.

3. 선택 사항: 이미 활동을 Intervals.icu에 동기화할 수 있는 시계 또는 트레이닝 앱.

Garmin이 없어도 사용할 수 있습니다. 자동 recovery evidence가 없으면 Coach는 누락된 데이터를 0이 아닌 unknown으로 처리합니다.

1. Hosted Coach에 연결

MCP endpoint:

https://mcp.paceandstaystrong.com/mcp

• claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → endpoint를 붙여넣기. 이 경로는 production OAuth, coaching turn, Intervals delivery 전체 검증을 거쳤습니다.

• ChatGPT: 전체 MCP(write/modify actions 포함)는 현재 OpenAI 공식 설명에 따라 ChatGPT Business, Enterprise, Edu의 웹 버전 beta로 제공됩니다. Pro의 custom MCP는 현재 read/fetch만 가능하여 이 Coach의 plan write/delivery 전체 흐름을 완료할 수 없습니다. workspace가 전체 MCP를 지원한다면 Apps/developer mode에서 custom app을 만들어 위의 remote endpoint를 지정하세요. 최신 플랜 제한은 OpenAI 공식 설명을 기준으로 합니다.

• OpenClaw: openclaw mcp add로 동일한 endpoint를 지정하고 --auth oauth를 추가하세요. 한 instance를 여러 사람이 사용한다면 OAuth identity를 per-requester로 설정해야 합니다. 그렇지 않으면 모든 사람이 동일한 Intervals 계정에 연결됩니다. 설정은 entrypoints/openclaw/를 참조하세요.

• 기타 MCP client: 동일한 URL을 remote Streamable HTTP MCP server로 설정하세요. 전체 흐름이 실제로 실행될 수 있는지는 해당 client가 이 제품이 필요로 하는 MCP/OAuth 동작을 지원하는지에 달려 있습니다.

각 entrypoint의 "전체 실기 검증 완료" 또는 "패키징 완료, 실제 연결 검증 대기" 상태는 entrypoints/를 기준으로 합니다.

2. Intervals.icu 인증

첫 연결 시 브라우저에서 Intervals.icu 동의 페이지가 열립니다. 본인의 Intervals.icu 계정으로 로그인하고 Coach가 필요로 하는 권한을 승인하세요:

• ACTIVITY:READ: 완료된 훈련 읽기.

• WELLNESS:READ: Intervals가 제공할 수 있는 wellness evidence 읽기.

• CALENDAR:WRITE: 훈련 캘린더 읽기/쓰기. 확인된 계획을 전달하고 read-back 검증을 할 수 있게 합니다.

• SETTINGS:WRITE: 설정 읽기. 확인된 delivery 흐름에서 실제로 필요할 때만, 누락되었고 evidence가 뒷받침하는 running threshold setting을 보충합니다.

Intervals 동의 페이지는 권한을 분리해서 표시합니다. 하나를 체크하지 않으면 해당 권한에 의존하는 기능이 명확하게 실패합니다. 다시 연결하여 권한을 보충하면 됩니다. Intervals 비밀번호, API key 또는 token을 대화에 붙여넣지 마세요.

3. 평범한 코치 질문을 바로 하세요

사전 설문 없이, 예를 들어:

讀我最近的訓練，告訴我這週該怎麼練。

또는:

我想提升 VO2max，又不想掉力量，幫我排第一個 28 天方向。

Coach는 먼저 이미 존재하는 evidence를 읽은 다음, 실제로 결정을 바꿀 수 있는 공백만 질문합니다. 예: 이번 주 훈련 가능일, 장비, 또는 provider가 알 수 없는 근력 운동 baseline.

4. 먼저 28일 preview를 보고 계획을 확인하세요

처음 계획을 만들 때 먼저 다음을 보게 됩니다:

• 이번 주: 정확하고, 실행 가능하며, 전달 가능한 session.

• 이후 3주: 방향성 outlook. 지금 모든 세부 사항을 안다고 가장하지 않습니다.

해당 preview를 확인한 후에야 계획이 기록됩니다. 이후의 매주 변경도 동일한 경험입니다:

before / after preview → 한 번 확인 → apply.

5. 캘린더에 보낼 때 delivery 확인을 하세요

전달은 또 다른 독립적인 확인입니다:

delivery preview → 한 번 확인 → Intervals.icu에 기록 → read-back 검증.

이 제품이 증명할 수 있는 최종 상태는 intervals_accepted입니다. Intervals 성공이 계획이 Garmin, Apple Watch 또는 다른 시계에 있다는 뜻은 아닙니다. Intervals 이후의 동기화는 외부 hop이며, 기기 경로별로 각각 검증해야 합니다.

Related MCP server: Transition MCP

Intervals.icu는 이 제품에서 어떤 역할을 하나요?

Intervals.icu는 현재의 interoperability hub입니다. Coach가 다양한 기기/앱의 활동과 wellness evidence를 받아들이도록 돕고, Coach가 확인한 캘린더 계획도承接합니다. Coach의 PlanState source of truth는 아닙니다.

手錶 / 訓練 app
      │
      ▼
 Intervals.icu ───── 已完成活動 + wellness evidence ─────► Coach
      ▲                                                   │
      │                                                   │
      └────────── 確認後的 calendar workout ◄────────────┘
      │
      ▼
Garmin / Apple Watch bridge / 其他下游同步

책임 분담:

• Intervals.icu: 외부 훈련 evidence를 통합하고 provider calendar를 보유합니다.

• Long Run Hybrid Coach: 유일한 current PlanState, decision history, athlete-reported evidence, 확인 binding, coaching workflow를 보유합니다.

• 사용자의 시계/앱: 활동을 Intervals로 가져올 수 있고, Intervals가 내려보내는 workout을 받을 수도 있습니다. 하지만 마지막 마일이 성공하는지는 독립적인 compatibility evidence입니다.

Intervals에 먼저 데이터가 있어야 하나요?

계정 자체만 필수 조건입니다. 활동/wellness가 이미 동기화되어 있으면 Coach의 자동 evidence가 더 완전해집니다. 없는 필드는 unknown으로 유지되며, 0으로 처리되지 않고, 선택적 수치 하나가 없다고 일반 coaching을 막지 않습니다.

기기가 측정하지 못했거나 동기화되지 않은 것은 대화에서 직접 말할 수 있습니다. 예:

• 근력 운동 실제 세트 수, 중량, 횟수;

• 이번 주 훈련 가능 시간과 장비 제한;

• 체중/체지방;

• 시계를 차지 않은 활동;

• "요즘 너무 피곤해" "잠을 잘 못 자" 같은 주관적 상태;

• 시계/앱에서 실제로 본 sleep, HRV, resting HR, readiness 등의 recovery reading.

Coach는 "피곤해"라는 한마디를 가짜 readiness score로 몰래 바꾸지 않습니다.

Hosted MCP vs Local / Self-hosted MCP

실제로 느껴지는 차이는 단 하나입니다: hosted는 휴대폰에서 바로 사용할 수 있고, local은 gateway를 실행하는 그 컴퓨터에서만 사용할 수 있습니다. 아래의 다른 모든 줄은 이 차이의 비용입니다.

Hosted MCP 최단 활성화 절차

1. 전체 요구 사항을 지원하는 MCP client에 remote MCP app/connector를 추가합니다.

2. URL에 https://mcp.paceandstaystrong.com/mcp를 붙여넣습니다.

3. client의 OAuth 흐름을 완료합니다.

4. 브라우저에서 Intervals.icu 동의를 승인합니다.

5. 채팅으로 돌아와 첫 번째 코치 질문을 바로 합니다.

Hosted 서비스는 dynamic client registration, PKCE, gateway token, per-athlete owner mapping을 자체 처리합니다. 일반 사용자는 owner id, athlete id, API key, Intervals client secret 또는 server environment variable이 필요 없습니다.

Local / Self-hosted MCP는 어떻게 실행하나요?

Repo는 Python 3.11을 사용하며, 제품 자체는 stdlib-only라서 런타임 Python package를 먼저 설치할 필요가 없습니다.

1. Repo를 clone합니다.

2. Intervals.icu에 OAuth application 생성을 신청합니다. Intervals의 현재 공개 절차는 Settings에서 셀프 서비스로 app을 추가하는 것이 아닙니다. 공식 OAuth 설명에 따라 app name, description, website, logo, privacy policy, redirect URI와 사용자의 Intervals ID를 제공하세요. app이 생성된 후에야 Settings에 나타나며, Manage App에서 client_id/secret을 얻을 수 있습니다. 절차는 Intervals.icu OAuth support를 참조하세요.

3. Intervals app에 gateway provider callback을 등록합니다: <gateway-origin>/oauth/callback. 로컬 client는 loopback을 사용할 수 있습니다. remote client는 도달 가능한 HTTPS/secure tunnel이 필요합니다.

4. gateway 필수 환경 변수를 설정합니다:

export GARMIN_COACH_LOOP_GATEWAY_STATE_ROOT="$HOME/.local/share/long-run-hybrid-coach-gateway"
export GARMIN_COACH_LOOP_TOKEN_HMAC_KEY="$(openssl rand -base64 32)"
export GARMIN_COACH_LOOP_INTERVALS_CLIENT_ID="..."
export GARMIN_COACH_LOOP_INTERVALS_CLIENT_SECRET="..."

5. 시작:

python3 -m garmin_coach_loop.cli serve-gateway --host 127.0.0.1 --port 8422

6. 로컬 MCP client가 다음을 가리키게 합니다:

http://127.0.0.1:8422/mcp

remote client에 정식으로 제공하려면 loopback 예시를 production runbook으로 사용하지 마세요. Persistent volume, TLS, trusted client origin, single replica, release identity, 배포 검증은 docs/deploy-gateway.md를 참조하세요.

Local CLI가 조용히 두 번째 current plan이 되어서는 안 됩니다

한 athlete는 하나의 current writer만 가져야 합니다. 로컬에서 GARMIN_COACH_LOOP_GATEWAY_URL이 hosted coach를 가리키도록 설정하면 로컬 store 쓰기는 기본적으로 차단됩니다. 명시적으로 --offline을 추가해야만 "의도적으로 별도의 local plan을 만들고 있다"는 의미가 됩니다.

이미 로컬 state가 있는 사람은 hosted로 이전할 수 있습니다. 전체 절차는 docs/ops/migrate-local-store-to-hosted.md를 참조하세요.

지금 무엇을 할 수 있나요?

현재 제품 기능은 다음과 같습니다:

• 28일 방향성 유지: 이번 주 정확한 session ＋ 이후 3주 outlook.

• Intervals activity/wellness/calendar evidence를 읽고, 신뢰할 수 있는 planned → actual 자동 reconciliation을 current plan에 반영.

• 동일한 주간 계획에서 러닝과 근력 운동을 동시에 처리.

• athlete-reported profile, availability, long-term goal, training preference, 실제 근력 운동, 체중/체지방, 기기가 기록하지 못한 활동, subjective state 기록.

• startCoachSession이 이번 request의 recovery readings를 수신. Hosted는 로컬 health database를 읽을 필요도 없고 읽지도 않습니다.

• 지원되는 형식의 CSV, Apple Health XML 내용, binary import path를 통한 FIT payload를 포함한 지원되는 과거 evidence 가져오기. 동일 파일과 동일 활동은 deterministic 중복 제거를 하며, 판단할 수 없을 때만 사용자에게 묻습니다.

• Session에 coach_note를 포함할 수 있어 코치의 핵심 텍스트가 Intervals event에 함께 들어갑니다. 몰래 두 번째 workout grammar를 만들지 않습니다.

• 매주 "실제로 무엇을 훈련했는지, 개선 evidence가 있는지, 다음 단계는 무엇인지"를 복기합니다. "계획을 완료했다"는 것을 fitness가 향상된 것으로 직접 간주하지 않습니다.

• 계획 변경은 먼저 preview 후 확인한 다음 apply.

• 캘린더 전달은 먼저 preview 후 확인. 안전한 retry, replace, product-owned event withdraw 지원.

• 대화에서 직접 내보내기 또는 2단계 영구 삭제로 이 제품이 보유한 owner data 삭제.

중요한 경계

• startCoachSession은 deterministic reconciliation을 수행하며 새로운 PlanState version을 기록할 수 있습니다. 완전히 side effect 없는 stored state만 원한다면 getCoachState를 사용하세요. 그것이 read-only 경로입니다.

• athlete-reported activity는 evidence이지만 provider-backed actual completion으로 몰래 승격되지 않습니다.

• recovery 숫자는 실제 관측값만 받습니다. 모델이 텍스트에서 스스로 숫자를 추측할 수 없습니다.

• 이 제품은 의료 진단을 하지 않습니다.

• Delivery evidence는 Intervals read-back까지만이며, 시계에 도달했다고 주장하지 않습니다.

데이터, 내보내기 및 삭제

Hosted 측은 동일한 owner 계획을 유지하는 데 필요한 제품 상태를 보관합니다: PlanState version chain, decision/receipt, athlete-reported evidence, identity mapping, 수렴되지 않은 delivery bookkeeping.

내보내기 시 의도적으로 포함하지 않는 것: OAuth credential의 keyed fingerprint, provider raw payload/GPS track, 내부 owner id. Fingerprint는 단방향 bookkeeping입니다. raw GPS/활동 파일은 provider가 제공해야 합니다. owner id는 내부 storage locator입니다.

제품 데이터 삭제에도 세 가지 명확한 경계가 있으며, 이 세 가지는 이 제품이 삭제할 수 있는 범위에 없습니다:

• 이미 Intervals.icu 캘린더에 기록된 workout;

• Intervals.icu Settings에서 부여한 provider 권한;

• plan, 건강 또는 identity 내용이 없는 최소화된 플랫폼 운영 기록.

전체 수명 주기는 docs/account-lifecycle.md를 참조하고, 공개 개인정보 정책은 paceandstaystrong.com/privacy.html에 있습니다.

현재 제한 사항

• Coach는 Apple Health, Garmin Connect 또는 다른 기기 계정에 직접 로그인하지 않습니다. 주요 자동 evidence 경로는 현재 Intervals.icu입니다.

• Hosted는 매 request로 전달된 raw recovery upload를 영구 보관하지 않습니다. 다음에 필요하면 그때의 evidence를 다시 전달하면 됩니다.

• 이 제품은 Intervals 이후의 모든 기기 동기화 hop을 관찰하지 않으므로 intervals_accepted를 "이미 시계에 있다"고 말하지 않습니다.

• Local self-hosting은 operator/developer 경로입니다. 일반 사용자는 Hosted MCP를 우선해야 합니다.

• 기기 호환성은 경로별 evidence이며, Garmin이 검증되었다고 다른 기기도 동일하다고 추론하지 않습니다.

제품 surface 및 기술 문서

현재 release는 외부에 22개의 MCP tool, 2개의 prompt, 30개의 CLI 명령, 3개의 JSON Schema contract, 5개의 identity 테이블을 제공합니다. 이 숫자는 테스트가 실제 코드에서 도출한 것으로, README가 스스로 어긋나는 것을 방지합니다.

• 안정적인 사용자 스토리: docs/user-story.md

• 데이터 소스 및 필드 경계: docs/data-sources.md

• Entrypoint 및 플랫폼 설정: entrypoints/

• MCP protocol, OAuth 및 tool 동작: entrypoints/mcp/README.md

• Hosted gateway 배포: docs/deploy-gateway.md

• 계정 수명 주기: docs/account-lifecycle.md

• 공개 출시/reviewer 자료: docs/distribution/

• Release inventory: docs/release-inventory.md

• Repository invariants 및 검증: AGENTS.md

Long Run Hybrid Coach는 독립 프로젝트이며 Garmin, Intervals.icu, Apple 또는 다른 기기/플랫폼 공급업체와 소속, 보증 또는 후원 관계가 없습니다. 코드는 MIT License로 공개됩니다.