AIm Workout Journal

AIm ワークアウトジャーナル

AI アシスタントが記録するワークアウトトラッカーです。AIm はMCP サーバーと**モバイルウェブアプリ（PWA）**で構成されています。Claude や ChatGPT で自分の言葉でセッションを説明すると、アシスタントが MCP 経由で記録し、アプリにプログラム、履歴、記録、推定 1RM、筋肉ごとの負荷が表示されます。サーバーは目標、けが、記録済みの重量をデータとしてアシスタントに渡すため、一般的なアドバイスではなく、実際のトレーニングに基づいて計画できます。

aim-journal.com で公開中です。無料で、2つ目のサブスクリプションに加入しなくても、すでに料金を支払っている AI サブスクリプション内で利用できます。ガイド： workout tracker を MCP 経由で接続する、 AI パーソナルトレーナー、 1RM 計算機。

仕組み

同じホストに接続方法が2つあり、どちらも同じ user_id に解決されます。

https://<app>/mcp                OAuth 2.1 — add as a connector, approve in the browser
https://<app>/{token}            mobile web app / installable PWA
https://<app>/{token}/mcp        the original connector address, still supported
https://<app>/{token}/api/*      read only JSON the UI consumes

OAuth は、現在コネクターが使用する方式です。サーバーは OAuth 2.1 リソースサーバーです。認証されていない呼び出しに対して、RFC 9728 の保護リソースメタデータを含む 401 を返し、クライアントはそこから認可サーバーを検出して動的に登録します。その後、ユーザーはこのアプリが提供する同意画面で承認します。Supabase Auth が認可サーバーであるため、認可コードやアクセストークンはここには保存されません。アクセストークンの sub は、users.supabase_user_id を通じてアカウントに紐付けられます。秘密情報を手作業で貼り付ける必要はありません。

URL トークンは OAuth より前から存在しており、現在も機能します。そのため、OAuth の導入後も、すでにユーザーの受信箱にあるリンクはすべて使い続けられました。トークンリゾルバーのミドルウェアが、先頭のパスセグメントをユーザーに対応付け、すべてのクエリを user_id でスコープします。一方、OAuth の経路では検証済みトークンから同じコンテキスト変数を設定します。入口は2つでも、スコープのルールは1つです。

MCP サーバーが提供するもの

ステートレスなストリーミング可能 HTTP（FastMCP）経由で20個のツールを提供します。

• 記録：log_session、update_session、update_set、delete_session、import_document（別のトラッカーからのエクスポートを貼り付けるか、ノートのページを撮影した写真を使用します）。
• 読み取り：get_sessions、get_session、get_stats（ボリューム、進捗、Epley 式による推定 1RM）、get_program、get_goals、get_body_metrics。
• カタログ：search_exercise_pool（イラスト付きの厳選されたグローバルプール）、list_exercises、upsert_exercise。
• コーチング：重要なのは get_coaching_context です。これはデータのみを返します。このユーザーの目標、経験、器具、けが（負荷がかかる動作パターンを含む）、最近のワーキングウェイト、目標に合った計画範囲、摂取状況を、作業内容（次のワークアウト、新しいプログラム、週次レビュー）に応じて返すため、アシスタントは何もないところからではなく、データに基づいて計画できます。アシスタントがこの情報をどのように使うかは、サーバーの MCP 指示に記載されています。review_program_draft、update_coach_profile、upsert_goal、log_coach_event、log_body_metric を使って、このコンテキストを最新の状態に保ちます。

リポジトリ構成

api/index.py      Vercel entrypoint (must stay at repo root, see below). Imports backend/src.
requirements.txt  Vercel's Python build reads this (must also stay at repo root).
backend/          Python package, tests, scripts, DB migrations.
web/              Vite + React SPA (own package.json, own dev server) and the static guide pages.

api/index.py と requirements.txt は移動できません。Vercel のゼロコンフィグ Python ビルダーは、ルートレベルの api/ にある関数のみを自動検出し、それらと同じ階層にあるルートレベルの requirements.txt のみをインストールするためです。.vercelignore によって、backend/ 内のその他すべて（pyproject.toml、uv.lock、tests、scripts、supabase/）は Vercel のビルド対象から除外されます。そのため Vercel は、このリポジトリを静的 SPA と1つの Python 関数として扱います。

読み進める前に知っておいてほしいことが1つあります。一部のコードコメントには、docs/COACHING_PLAN.md、docs/TEST_CASES.md、docs/DEPLOYMENT.md など、パスを使って内部の計画文書を参照しているものがあります。これらは公開されていない製品や調査に関するメモのため、パスをたどってもファイルは見つかりません。コードはそれらに依存していません。これらのパスは判断の出典を示すものであり、依存関係ではありません。このリポジトリの内容をビルド、テスト、実行するために必要な情報は、すべてこの README に記載されています。

スタック

• バックエンド（backend/）：Python 3.12、FastMCP（ステートレス HTTP）、psycopg3、Supabase Postgres （トランザクションプーラー）。MCP と読み取り API は backend/src/workout_storage/ にあり、 api/index.py で配信されます。
• フロントエンド（web/）：Vite、React、Tailwind v4、shadcn/ui、recharts、React Query、 vite-plugin-pwa。データレイヤーは web/src/app/lib/ にあります（トークンから API、アダプター、フックの順）。web/guides/ のガイドページは ビルド時に静的 HTML として生成され、バンドルを含みません。
• ホスティング：Vercel プロジェクトを 1 つ使用します。vercel.json は MCP、API、cron を関数にルーティングし、 それ以外はすべて SPA にルーティングします。

フロントエンドの開発

cd web
npm install
echo 'VITE_API_ORIGIN=https://workout-storage.vercel.app' > .env.local  # dev against prod API
npm run dev              # http://localhost:5173/{token}
npm run test             # vitest: pure function + component tests
npx playwright install chromium   # one time, before the first test:e2e run
npm run test:e2e         # Playwright, against /demo (no backend needed)

バックエンドの開発

cd backend
uv sync --extra dev           # install deps
cp ../.env.example ../.env     # fill DATABASE_URL etc. (kept at repo root, shared by all tooling)
uv run pytest                  # unit + integration + e2e
uv run ruff check . && uv run mypy .

ユーザーを作成します（ブラウザーで開くためのトークンと、アシスタントに貼り付けるためのトークンが出力されます）：

cd backend
uv run python scripts/create_user.py --name "Alex"

独自の環境で実行する

必要なものはすべてここにありますが、これはすぐに使えるセルフホスト用キットではなく、ホスティングサービスのソースコードです。Supabase プロジェクト（マイグレーションは backend/supabase/migrations/ にあります）、Vercel プロジェクト、および .env.example に記載されている環境変数をご用意ください。分析、メール、バックアップの連携は任意で、キーが設定されていない場合は動作しません。

クレジット

エクササイズのイラストは、CC BY-SA の下で提供されるサードパーティーの作品です。それぞれのクレジットは web/ATTRIBUTIONS.md に記載されています。このリポジトリのライセンスにかかわらず、各作品には独自のライセンスが適用されます。

ライセンス

MIT です。詳細は LICENSE をご覧ください。エクササイズのイラストは唯一の例外です。上記の「クレジット」をご覧ください。