FitCoach MCP

Claude や ChatGPT を、記憶を持つフィットネスコーチに変えるリモート MCP サーバーです。永続的な目標、会話形式のワークアウト記録、ユーザーごとのパラメータ調整、そして「plan my sessions」という毎週の儀式を備え、バージョン管理され説明付きのトレーニングプランを生成します。

役割分担: LLM は会話を捉えて説明する役割を担い、src/engine/ 内の決定論的エンジンがすべてのプログラミング上の決定（進行、ボリューム、ディロード、エクササイズ代用、ランのペーシング、自動調整）を下します。同じ入力からは、常に同じプランが生成されます。

事実は一箇所に集約される

docs/CURRENT-STATE.md が、カウント、定数、デプロイ環境の識別、そして構築済みかどうかについての唯一の正義です。この README は、意図的にその内容を極力繰り返さないようにしています。これは、2026年8月の監査で、このファイル・RUNBOOK・SUBMISSION-PACK が、実数が22にもかかわらずそれぞれ独立して11ツールと主張していることが判明したためです。ここにある数字が CURRENT-STATE と矛盾する場合は、CURRENT-STATE が優先され、このファイルは古いことがわけです。CURRENT-STATE がコードと矛盾する場合は、まず CURRENT-STATE を修正してください。

Related MCP server: WorkoutGuide MCP

プロダクトの仕組み

• 生のログは追記専用です。 セッション、セット、フィードバック、ラン、リカバリーメトリクスは一切編集されません。知的作業はすべて、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」です。 現在はすべてのゲートが解除されており、トライアル時計は開始されません。ゲート自体は完全に構築・テスト済みで、このフラグが単に開いてるだけです。CURRENT-STATE → Entitlements を参照してください。

• セーフティスクリーン。 src/server/safety.ts は、src/server/tools.ts の sourceTexts() に列挙された全9つのユーザーフリーテキスト表面に対して、決定論的な危険信号マッチャーを実行します。緊急レベルに一致した場合は、応答から他のすべて（アップグレードフッターを含む）を削除します。この処理は、エンタイトルメント制限されたパスでも実行されるため、胸の痛みを報告した制限中のユーザーには、営業トークではなくエスカレーションが渡ります。

クイックスタート（ローカル）

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 にコピーしても効果はありません。上記のように変数をインラインで渡すか、エクスポートするか、自分で --env-file=.env を付けてください。

起動後、2つのプローブがあり、その2つの違いは重要です。curl localhost:3000/healthz はデータベースに触れずに {"ok":true} を返します（死活監視用です。Fly が30秒ごとにポーリングするため、DB の障害で失敗してはなりません）。curl localhost:3000/readyz は実際にクエリを実行し、{"ok":true,"db":"up","durationMs":N} または 503 の db:down を返します。外部の監視が見ているのは /readyz です。

dev モードでは、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 + マイグレーションを dist/ へコピー）、npm start（ビルドの実行）、npm run test:watch、npm run provision（Supabase）、npm run seed-demo、npm run metrics、npm run deploy（デプロイ参照）。

ストレージ

バックエンドを選ぶ関数は1つだけです。src/storage/select.ts の createStorage() で、src/server/index.ts から一度だけ呼び出されます。

「本番同等」とは、NODE_ENV=production または AUTH_MODE=supabase のことです。この拒否は意図的です。fly.toml では DATA_DIR が設定されていないため、以前の PGlite フォールバックはインメモリでした。つまり、サーバーは問題なく起続し、/healthz は緑のままで、ツールは動作し、すべてのユーザーがまっさらな空のアカウントを作成し、再起動のたびにまた空のアカウントが作られました。シークレットの消失は、健全なデプロイとまったく同じに見えていました。現在は、代わりに明確に失敗します（tests/storage-select.test.ts）。

どちらも同じ Storage インタフェースを完全に実装しており、同じマイグレーション（src/storage/migrations/ の 0001_init 〜 0015_rls_v7、RLS ポリシーは対になる _rls_ ファイル内）を実行します。PGlite はスタブではなく、Postgres は将来の作業ではありません。PostgresStorage は完全に実装されて出荷されており、現在のデプロイが実行しているものです。バックエンド間でズレがあいけない唯一のクエリ、つまりポピュレーションチューニング集計クエリは、src/storage/tuning-shared.ts から完全に共有されています。

PostgresStorage.init() は起動時にすべてのマイグレーションを順番に適用します。それらのプレーンなファイルは、追加的かつ中党であるため、稼働中のデータベースに対する再実行も安全です。_rls_ ファイルは Supabase の auth.uid() を参照するもので、接続先データベースがそれを提供している場合にのみ自動的に適用され、ローカル開発や CI の素の Postgres ではスキップされます。

実際の DATABASE_URL がない場合に、テスト71件がスキップされる点に注意してください。リリース前には、PGlite だけでなく Postgres に対してテストスイートを実行してください。

デプロイ

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 にありますが）が、アプリを単一マシンに固定します。これはプロセス内レートリミッターが依存しているものです。詳細は 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 です。

ドキュメント