FitCoach MCP

Claude 또는 ChatGPT를 메모리를 갖춘 피트니스 코치로 만들어 주는 원격 MCP 서버입니다. 지속적인 목표, 대화형 운동 기록, 사용자별 파라미터 피팅, 그리고 버전이 매겨지고 설명이 포함된 훈련 계획을 생성해 주는 주간 "plan my sessions" 리추얼을 제공합니다.

분업 구조: LLM은 대화를 포착하고 서술합니다. src/engine/ 속 decisive한 엔진이 모든 프로그래밍 결정(진행률, 볼륨, 딜로드, 운동 대체, 러닝 페이스, 자동 조절)을 내립니다. 같은 입력이면 언제나 같은 계획, 언제나 그렇습니다.

사실은 한곳에 있다

docs/CURRENT-STATE.md는 개수, 상수, 배포 정체성, 그리고 구축된 것과 구축되지 않은 것에 대해 소스 오브 트루스(source of truth) 입니다. 이 README는 의도적으로 그 내용을 최대한 조금만 다시 옮깁니다. 2026년 8월 감사에서 이 파일, RUNBOOK, 그리고 SUBMISSION-PACK가 각각 독립해서 도구가 11개라고 주장하고 있었는데 실제로는 22개였기 때문입니다. 여기 적힌 숫자가 CURRENT-STATE와 어긋나면 CURRENT-STATE가 우선이고, 이 파일이 stale합니다. CURRENT-STATE과 어긋나면 코드를 수정하세요, 아니면 CURRENT-STATE부터 고치세요.

Related MCP server: WorkoutGuide MCP

제품 기제

• 원시 로그는 추가 전용(append-only)입니다. 세션, 세트, 피드백, 러닝, 회복 지표는 절대 편집되지 않습니다. — 사용자 지능이 필요한 모든 것은 user_params의 파생 상태(e1RM, 추세, 정체 구간 감지, 회복 점수, 볼륨 랜드마크, 러닝 피트니스)이며, 계획 호출할 때마다 반복됩니다.

• 플랜은 버전 관리됩니다. 모든 plan_my_week는 이전 리비전을 대체하면서 상위 포인터 + 인간이 읽는 이유를 남깁니다 — "git 갈고리, 빼기는 git."

• 체험판은 시간이 아니라 훈련 블록입니다. TRIAL_DAYS = 35(28일 메조사이클 + 7일 유예), 첫 log_workout, plan_my_week, log_run부터 시작합니다. 온보딩과 import_history는 의도적으로 체험 기간을 시작하지 않습니다. 읽기 도구는 절대 있지 않고 delete_my_account는 게이트되지 않습니다 — 당신을 위한 데이터는 당신 것.

• 업그레이드는 대화 중에 일어납니다. 차단된 쓰기 도구는 오류가 아닌 도구 내용으로 따뜻한 업그레이드 메시지를 반환하기 때문에, 모델이 사용자 의도가 있는 시점에 자연스럽게 전달합니다.

• EARLY_ACCESS는 현재 ON이므로 지금은 아무것도 게이트되지 않고 체험 시계도 시작하지 않습니다. 게이트는 완전히 구현되고 테스트되어 있으며, EARLY_ACCESS 플래그가 그 게이트를 열어 두고 있는 것입니다. CURRENT-STATE → Entitlements를 참고하세요.

• 안전 화면. src/server/safety.ts는 9개의 사용자 자유 입력 표면 전체에 대해 deterministic 매칭기(레드 플래그)을 실행하는데, 모든 표면은 freeTextSources()와 바이탈 표면 집합이 확인되는 한 곳, 즉 src/server/tools.ts에 열거되어 있습니다. 응급 상황 매칭이면 응답에서 다른 것을 싹 빼서 업그레이드 푸터조차 없앱니다. 차단된 경로에서도 이 안전 화면이 실행되므로, 게이트되어 있는 사용자가 가슴 통증을 신고하면 구매 제안 대신 조치를 받게 됩니다.

빠른 시작 (로컬)

npm install
npm test                       # full suite; see CURRENT-STATE for the current count
AUTH_MODE=dev npm run dev      # Streamable HTTP MCP server on :3000

AUTH_MODE는 필수이고 명시적으로 지정해야 합니다 — 이 값이 설정되지 않거나 dev / supabase 이외인 경우 서버는 시작을 거부합니다.

Fatal startup error: Error: Unknown or missing AUTH_MODE null. Set AUTH_MODE=dev or AUTH_MODE=supabase

이 리포지토리는 .env 파일을 로드하지 않습니다. 즉 dotenv 의존성도 없고 dev 스크립트에 --env-file 플래그도 없습니다. .env.example은 변수 목록을 설명하기 위한 것이지, .env로 복사해도 아무 효과가 없습니다. 변수를 인라인(위 예시처럼)으로 전달하거나 export, 아니면 --env-file=.env를 붙이면 됩니다.

서버가 뜨면 두 가지 probe가 있고, 차이는 분명합니다: curl localhost:3000/healthz는 데이터베이스에 접촉하지 않은 채 {"ok":true}를 반환합니다(liveness를 위한 것으로, Fly가 30초마다 폴링하는 것이어서 DB가 문제여도 실패하면 안 됩니다). curl localhost:3000/readyz는 실제 쿼리를 날려서 {"ok":true,"db":"up","durationMs":N}을 반환하거나, 503 db:down을 반환합니다. 외부 모니터링이 주시하는 값은 /readyz입니다.

dev 모드에서는 Authorization 토큰 dev-<name>가 사용자 <name>으로 인증되고, NODE_ENV=production일 때는 아예 거절합니다.

Claude(사용자 지정 커넥터)나 MCP Inspector에서 URL을 http://localhost:3000/mcp, 헤더 Authorization: Bearer dev-henry로 연결한 다음, 프로필 만들기, 목표 설정, 운동 로그, 그리고 plan my week를 실행해 보세요.

기타 스크립트: npm run build (tsc + migrations를 dist/로 복사), npm start (빌드를 실행), npm run test:watch, npm run provision (Supabase), npm run seed-demo, npm run metrics, npm run deploy (뒤의 Deploying 참고).

스토리지

하나의 함수가 백엔드를 결정합니다. src/storage/select.ts의 createStorage()이며, src/server/index.ts에서 단 한 번 호출됩니다.

'production급'이란 것은 NODE_ENV=production 이거나 AUTH_MODE=supabase를 의미하며, 거부는 의도된 것입니다. DATA_DIR은 fly.toml에 없습니다. 따라서 기존에 사용하던 PGlite 폴백은 *완전히 메모리 내(in-memory)*에 지나지 않았습니다: 서버가 깨끗하게 부팅되고, /healthz가 계속 정상이며, 도구 호출은 모두 되었지만, 사용자마다 매번 빈 계정이 생성되고 재시작할 때마다 그 계정이 위에 다시 비워져 있었습니다. 즉, secret를 잃고 있어도 정상 배포로 보이는 일이 생겼습니다. 이제는 대신 명확하게 실패합니다(tests/storage-select.test.ts).

두 백엔드 모두 같은 Storage 인터페이스의 완전한 구현이며, 같은 마이그레이션을 실행합니다(0001_init … src/storage/migrations/, 프로덕트 내 0015_rls_v7 등, RLS 정책은 짝지는 _rls_ 파일에). PGlite은 테스트용이지 진짜 스텁이 아니고, Postgres도 나중에 하겠다는 것 아닙니다. PostgresStorage 완전한 출시 구현체이며 현재 상용 배포가 사용하는 것도 바로 PostgresStorage입니다. 두 백엔드가 어긋나면 안 되는 오직 하나의 집계, 조정 전용 집계는, src/storage/tuning-shared.ts에서 그대로 공유됩니다.

PostgresStorage.init()은 시작할 때 모든 마이그레이션을 순서대로 적용합니다. 이식 가능한 파일들은 추가적이고 원자력적(idempotent)이므로 라이브 데이터베이스에 다시 적용해도 안전합니다. _rls_ 파일들은 Supabase의 auth.uid()를 참조하며, 접속된 데베만 그 함수를 노출했다면 자동으로 적용됩니다. 평범한 Postgres를 쓰는 로컬 개발이나 CI에서는 건너뜁니다.

실제 DATABASE_URL이 있지 않으면 71개의 테스트가 스킵된다는 점을 알아두세요. 몰아서가 아니라 반드시 Postgres 상대로 한 스윗을 릴리즈 전에 돌려보세요.

Deploying

Fly 앱은 fitcoach-hs — 패키지 이름이 아니라 앱 이름입니다. 그래서 fly.toml과 scripts/deploy-fly.sh 모두 그 이름을 지정하므로, 일반적인 배포 명령만으로 올바르게 됩니다:

FLY_API_TOKEN=... npm run deploy

(0.7.1까지 두 파일 모두 fitcoach-mcp를 기본값으로 하고 있어서, 인자 없는 배포가 이 앱을 새로 만든 뒤 여기에 배포하여 그 URL을 헬스체크했습니다 — 아무도 사용하지 않는 앱에 대해 에패 그린이었습니다. 그때 만든 불청한 fitcoach-mcp 앱이 아직 Fly 계정에 남아 있다면, flyctl apps destroy fitcoach-mcp로 지우세요. /healthz에 응답하는 간첩 유사 앱이 아예 없는 것보다 대체로 나쁩니다.)

fly.toml에 [[mounts]] 볼륨 선언이 있어, 이는 의도된 것입니다 — 실행 중인 컴퓨터와 맞춰져 배포시 어떤 안내 문구로 안 되도록 합니다. 볼륨 자체는 미사용하지만(제품 데이터는 외부 Postgres에 있음), 앱을 반드시 단일 머신에 고정하는 용도가 있고, 그것에 프로세스 속도 제한기(rate limiter)가 의존합니다. 자세한 것은 docs/DEPLOY-NOTES.md에 있습니다.

아키텍처

src/
  types.ts            # binding contracts: domain, Storage, Engine, TOOL_NAMES
  storage/
    migrations/       # 0001..0015; portable DDL + paired Supabase RLS policies
    select.ts         # createStorage(): DATABASE_URL ? Postgres : PGlite
    postgres.ts       # production Storage impl (Supabase Postgres)
    pglite.ts         # dev/test Storage impl (embedded Postgres)
    tuning-shared.ts  # the aggregates-only tuning evidence SQL, shared by both
    seed-exercises.ts # exercise catalog: substitutes, movement pattern, fatigue cost
  engine/             # deterministic; see docs/INTELLIGENCE-DESIGN.md
    e1rm.ts           # Epley + RPE→RIR adjustment
    fitting.ts        # fitParams: e1RM smoothing, trends, stalls, freshness, landmarks
    planner.ts        # planWeek: splits, progression, deloads, hybrid day layout
    running.ts        # run fitness, program-mode arbitration, run-week construction
    adjust.ts         # same-day autoregulation (short on time / beat up)
    alignment.ts      # goal-vs-behaviour drift detection, proactive check-ins
    experiments.ts    # 2-week n-of-1 plateau tests
    recap.ts          # weekly recap + PR detection
    tuning.ts         # bounded population tuning from aggregate evidence
  server/
    index.ts          # express + stateless StreamableHTTP, per-request server factory
    auth.ts           # dev tokens / Supabase JWT (JWKS) + RFC 9728 metadata
    consent.ts        # OAuth 2.1 consent UI (Supabase as authorization server)
    entitlements.ts   # mesocycle trial gate + EARLY_ACCESS
    metering.ts       # idempotent usage events
    safety.ts         # deterministic red-flag screen (emergency / injury)
    temporal.ts       # server-side, timezone-aware natural-language dates
    rate-limit.ts     # in-process burst + sustained limits
    tools.ts, tools-*.ts, tools/*.ts   # the tool surface (see CURRENT-STATE)
    pages/, site.ts, share.ts, ui/     # landing, /connect, /docs, share links
  billing/provider.ts # BillingProvider interface + StubBillingProvider

실제로 연결된 결제 프로바이더는 없습니다. 동작하고 있는 것은 StubBillingProvider이고 CHECKOUT_BASE_URL도 설정되어 있지 않으므로, 결제 링크는 라이브 환경의 /#pricing 섹션으로 폴백합니다. 결제 Stripe 연동은 런북의 Phase 4에서 다루는 항목입니다.

문서