HevyMCP - AI-Powered Fitness Assistant

🚀 HevyMCP - AI を活用したフィットネスアシスタント＆MCP サーバー

HevyMCP は、Hevy フィットネスアプリ向けの AI を活用した Model Context Protocol（MCP）サーバーです。自然言語、ウェブインターフェース、または Claude や ChatGPT などの AI アシスタントを使って、ワークアウトの記録、エクササイズの検索、ルーティンの管理などを行えます。

---

🌟 機能

• 自然言語によるワークアウトの記録（「ベンチプレス 135 lbs で 3x8」）
• スマートなエクササイズのマッチング（あいまい検索、NLP、ユーザーの設定）
• ルーティンとフォルダーの管理
• Webhook サブスクリプション
• モダンなウェブインターフェース（デモモードと実モード）
• AI アシスタント向け MCP サーバー

---

⚡ クイックスタート

🎮 Playground で試す（インストール不要）

Smithery Playground ですぐに HevyMCP を体験できます：

npx -y @smithery/cli install hevymcp --client claude

または、Smithery MCP Registry にアクセスして「hevymcp」を検索してください。

📦 ローカルインストール

1. 依存関係をインストールする

pip install -r requirements.txt

2. Hevy API キーを設定する（実際に使用する場合）

# Create .env file
echo "HEVY_API_KEY=your_hevy_api_key_here" > .env

3. ウェブインターフェースを起動する

python -m uvicorn app.main:app --reload --port 8000

• 次の URL にアクセスしてください：http://localhost:8000

デモモードの場合（API キー不要、サンプルデータのみ）：

export DEMO_MODE=true
python -m uvicorn app.main:app --reload --port 8000

---

🖥️ ウェブインターフェース

• ワークアウトの記録、検索、筋肉群の閲覧をすぐにお試しいただけます。
• デモモード： 公開デモサイト専用です。API キーは不要で、一般公開で安全に使用でき、サンプルデータのみを扱います。
• 実モード： ローカルインストール向けです。実際に記録するには API キーを入力してください（ローカルでのみ使用され、第三者に送信されることはありません）。ローカルではデモモードを使用しないでください。

---

🛠️ API エンドポイント（開発者向け）

ルーティン

• GET /mcp/routines — すべてのルーティンを一覧表示
• POST /mcp/routines — 新しいルーティンを作成
• GET /mcp/routines/{routine_id} — ID でルーティンを取得
• PUT /mcp/routines/{routine_id} — ルーティンを更新

ルーティンフォルダー

• GET /mcp/routine-folders — すべてのフォルダーを一覧表示
• POST /mcp/routine-folders — 新しいフォルダーを作成
• GET /mcp/routine-folders/{folder_id} — ID でフォルダーを取得

Webhook

• GET /mcp/webhooks — すべての Webhook サブスクリプションを一覧表示
• POST /mcp/webhooks — Webhook を作成
• DELETE /mcp/webhooks/{webhook_id} — Webhook を削除

その他のエンドポイント

• POST /mcp/workout — ワークアウトを記録（NLP）
• GET /mcp/workouts — 最近のワークアウトを一覧表示
• GET /mcp/exercises/search?query=bench — エクササイズを検索
• GET /mcp/exercises/muscle-groups — 筋肉群を一覧表示

---

🤖 MCP ツール（AI アシスタント向け）

ワークアウトツール

• log_workout — 自然言語でワークアウトを記録（「ベンチプレス 135 lbs で 3x8」）
• get_workout_history — ページネーション付きで最近のワークアウトを一覧表示
• get_workout_count — ワークアウトの統計情報を取得
• get_workout_events — ワークアウトの更新・削除イベントを取得

エクササイズツール

• search_exercises — あいまい検索で名前からエクササイズを検索
• get_muscle_groups — 利用可能なすべての筋肉群を一覧表示
• get_exercises_by_muscle_group — 筋肉群で絞り込んだエクササイズを取得
• update_exercise_template — 既存のエクササイズテンプレートを変更
• delete_exercise_template — エクササイズテンプレートを削除

ルーティン管理

• list_routines — ページネーション付きでワークアウトルーティンをすべて一覧表示
• create_routine — 新しいワークアウトルーティンを作成
• get_routine — ID で特定のルーティンを取得
• update_routine — 既存のルーティンを変更
• delete_routine — ルーティンを削除

フォルダーの整理

• list_routine_folders — すべてのルーティンフォルダーを一覧表示
• create_routine_folder — 整理用フォルダーを作成
• get_routine_folder — ID でフォルダーの詳細を取得
• update_routine_folder — フォルダーのプロパティを変更
• delete_routine_folder — フォルダーを削除

Webhook 連携

• list_webhooks — すべての Webhook サブスクリプションを一覧表示
• create_webhook — リアルタイムイベントのサブスクリプションを作成
• delete_webhook — Webhook サブスクリプションを削除

---

🧩 API 構成（コントリビューター向け）

• app/integrations/hevy_api.py — Hevy API クライアント（新しいエンドポイントはここに追加します）
• app/endpoints/ — FastAPI エンドポイント（新しいルートはここに追加します）
• app/mcp_server.py — MCP ツールの定義とハンドラー
• app/web_interface.py — Web UI のロジック（デモモードと実モード）

---

🛡️ 安全性とプライバシー

• デモモード： API キーは不要で、データは保存されず、公開デモでも安全に使用できます。
• 実モード： API キーはローカルでのみ使用され、第三者に送信されることはありません。
• 実際の API キーを公開サーバーや共有サーバーに入力しないでください！

---

🤝 コントリビュート

1. このリポジトリをフォークしてクローンします。
2. 仮想環境を作成します：

   python -m venv venv
   source venv/bin/activate
   

3. 依存関係をインストールします：

   pip install -r requirements.txt
   

4. 新しいエンドポイント／ツールを追加します：
   • hevy_api.py（API クライアント）に追加します
   • endpoints/（FastAPI）に追加します
   • mcp_server.py（MCP ツール）に追加します
5. プルリクエストを作成してください！

---

💬 ご質問はありますか？

• GitHub でイシューまたはディスカッションを作成してください。
• プルリクエストやフィードバックを歓迎します！