Trainzilla Mcp

tzilla-mcp（MVP、ローカル専用）

MCP クライアント （Claude Desktop、Claude Code、Cursor、…）をTrainzilla のコーチとして利用できるローカルのMCPサーバーです。既存の GraphQL API（api.tzilla.live）をラップしており、データベースに直接アクセスすることはありません。そのため、すべての認証とビジネスルールはバックエンドで適用されます。

ステータス：ローカル MVP — 読み取りツール、オフライン計算ツール、確認が必要な書き込みツールに加え、リソースとプロンプトを備えています。どこにもデプロイされていません。お使いのマシン上で、コーチのログイン情報を使って動作します。

現在できること（ツール 94 個、リソース 1 個、プロンプト 1 個）

読み取り（ライブデータ）：

• whoami、list_clients、get_client_profile
• list_client_habits、get_habit_compliance、recent_habit_activity、master_habits
• list_workout_plans、list_diet_plans
• list_checkins、list_sessions、list_subscriptions、billing_summary

計算（オフライン、ネットワーク不要）：

• calc_tdee — BMR／TDEE／推奨カロリー
• calc_macros — 戦略別のマクロ栄養素配分（標準 40/30/30、プロ g/kg、ケト）
• calc_1rm — 1 回最大重量（Epley）と %1RM に基づく重量の提案

書き込み（確認が必要）： すべての書き込みツールは、confirm: true を指定して呼び出さない限りプレビューを返すため、意図せず変更されることはありません。

• create_habit、create_master_habit、assign_master_habit
• create_checkin（質問付き）、schedule_session
• create_workout_plan、create_diet_plan

公開していない機能： 削除、決済処理／返金、メッセージ送信、権限変更 — 意図的に対象外としています。

リソース： tzilla://client/{clientId}/profile — クライアントのプロフィール（JSON）。

プロンプト： weekly_client_review — プロフィール／習慣／遵守状況／セッションを取得し、読み取り専用の週次レビューを作成します。

セットアップ

npm install
npm run build

コーチのトークンを記載した .env を作成します（.env.example を参照）。最も簡単な方法は、コーチ用 Web アプリにログインして、ブラウザーのコンソールで次を実行することです。

localStorage.getItem("token")        // -> TZ_ACCESS_TOKEN
localStorage.getItem("refreshToken") // -> TZ_REFRESH_TOKEN

トークンの有効期限が切れると、サーバーは refreshAccessToken を使ってアクセストークンを自動更新します。

実行

ローカル（stdio） — Claude Desktop などで使用：

• 開発： npm run dev
• ビルド済み： npm start
• スモークテスト： node scripts/smoke.mjs

リモート（Streamable HTTP） — localhost 限定、複数コーチ対応：

• 開発： npm run http · ビルド済み： npm run start:http
• http://127.0.0.1:8787/mcp でリッスンします（MCP_HTTP_PORT／MCP_HTTP_HOST を設定してください）。
• スモークテスト： node scripts/smoke-http.mjs

認証モード

• stdio： 環境変数の TZ_ACCESS_TOKEN（および TZ_REFRESH_TOKEN）を使用し、自動更新します。
• エンドポイントの選択：
  • TZ_API_URL が設定されている場合は、それを使用します。
  • それ以外の場合、TZ_ENVIRONMENT=staging では https://qa-be2.tzilla.live/graphql を使用します。
  • その他の場合はすべて、デフォルトで https://api.tzilla.live/graphql を使用します。
• HTTP： パススルー方式 — リクエストごとに、コーチのAPI キー（Authorization: Bearer tz_... または x-api-key）を送信する必要があります。サーバーはトークンを保存せず、呼び出し元のキーを GraphQL API に転送するため、バックエンドでスコープが適用されます（複数コーチで安全に利用できます）。API キーは以下のバックエンド機能で発行します。

バックエンド：トレーナー API キー（tzilla-be に実装、ローカルのみ — 未デプロイ）

• createApiKey(name) → 平文の tz_… キーを一度だけ返します（情報も含む）
• apiKeys（一覧、秘密情報なし） · revokeApiKey(id)
• 認証ミドルウェアは tz_ キー（x-api-key または Bearer ヘッダー）を受け付け、所有するコーチを特定し、lastUsedAt を記録します。保存されるのは SHA-256 ハッシュのみです。

Claude Desktop から使用する

claude_desktop_config.json に追加します（Settings → Developer → Edit Config）。

{
  "mcpServers": {
    "tzilla-coach": {
      "command": "node",
      "args": ["C:/New folder/tzilla-mcp/dist/index.js"],
      "env": {
        "TZ_API_URL": "https://api.tzilla.live/graphql",
        "TZ_ACCESS_TOKEN": "<paste>",
        "TZ_REFRESH_TOKEN": "<paste>"
      }
    }
  }
}

Claude Desktop を再起動して、次を試してください：「t zilla-coach を使って、自分が誰かを確認し、クライアントの一覧を表示してください。」

ロードマップ

• 書き込みツール（習慣、チェックイン、セッション、プラン）— 確認後に実行
• リソース（クライアントプロフィール）＋プロンプト（週次レビュー）
• 読み取り対象の拡大（プラン、チェックイン、セッション、請求）
• バックエンドのトレーナー API キー／PAT（tzilla-be に組み込み済み、ローカル — PR とデプロイが必要）
• リモートの Streamable-HTTP トランスポート（localhost、API キーのパススルー認証）
• バックエンドの API キー機能をデプロイし、実際のリモート利用向けに HTTP サーバー（TLS）をホストする
• 公開コネクター向けに完全な MCP OAuth 2.1 を導入する（パススルーを置き換え）
• リソース（プラン／チェックイン履歴）とプロンプト（例：「プランを作成する」）を追加する

レイアウト

src/
  config.ts   # env + tiny .env loader
  client.ts   # GraphQL client: bearer auth + refresh-on-401 + role header
  calc.ts     # offline coach math (ported from HealthMath/WorkoutMath)
  index.ts    # MCP server + tool definitions (stdio)
scripts/
  smoke.mjs   # spawns the server and lists tools (handshake check)