Habitica Mcp Server

Habitica MCP Server

中文文档请阅读 README.zh-CN.md

AI アシスタントが Habitica API とシームレスに連携し、タスクの作成、習慣の記録、ペットの育成、ゲーム感覚での生産性向上を実現する Model Context Protocol（MCP）サーバーです。

✨ 機能

🎮 ゲームプレイの主な機能

• 📋 スマートなタスク管理 – あらゆる種類のタスクを作成／表示／更新／削除できます
• ✅ チェックリスト管理 – タスク内のチェックリスト項目を追加、更新、削除し、スコアを記録できます
• 🎯 習慣の記録 – 習慣の達成を記録し、健康的なルーティンを築けます
• 🐾 ペットの育成 – ペットを孵化させて餌を与え、成長を見守れます
• 🏇 マウントのコレクション – さまざまなマウントを管理し、装備できます
• 🛍️ ショップと報酬 – ゲーム内アイテムを閲覧して購入できます
• ⚡ スキルシステム – クラススキルを使ってゲームプレイを強化できます

📊 データ関連機能

• 👤 ユーザープロフィール – ユーザーの詳細情報や統計を取得できます
• 🏷️ タグ管理 – タグを作成、管理して、整理しやすくできます
• 📬 通知センター – システム通知を確認、管理できます
• 📦 インベントリ – 所有しているすべてのアイテムと装備を一覧表示できます

🤖 AI 連携の特長

• 🧠 自然言語での操作 – 会話を通じて Habitica を操作できます
• 📝 タスクの提案 – AI がリクエストに応じてタスクを作成できます
• 📈 進捗レポート – 進捗を自動的に追跡し、要約できます
• 🎨 パーソナライズされた体験 – 習慣に合わせたおすすめを提案します

🚀 クイックスタート

前提条件

• Node.js 18+
• npm または yarn
• 有効な Habitica アカウント

インストール

1. リポジトリをクローンする

git clone https://github.com/ibreaker/habitica-mcp-server.git
cd habitica-mcp-server

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

npm install

3. API 認証情報を設定する（次のセクションを参照）

4. サーバーを起動する

npm start

⚙️ 設定

Habitica API 認証情報を取得する

1. Habitica にログインします
2. アバターをクリックし、設定を選択します
3. API タブを開きます
4. User ID と API Token をコピーします

環境変数

方法 A：変数をエクスポートする

export HABITICA_USER_ID="your-user-id"
export HABITICA_API_TOKEN="your-api-token"

方法 B：.env ファイル

HABITICA_USER_ID=your-user-id
HABITICA_API_TOKEN=your-api-token

⚠️ セキュリティに関する注意： API キーをバージョン管理にコミットしないでください。

🎯 使い方

サーバーを起動する

# Production
npm start

# Development (with reload)
npm run dev

MCP クライアントとの連携

このサーバーは MCP 仕様に準拠しており、MCP に対応するあらゆる AI クライアントで使用できます。Claude Desktop の設定例：

{
  "mcpServers": {
    "habitica-mcp-server": {
      "command": "npx",
      "args": ["-y", "habitica-mcp-server"],
      "env": {
        "HABITICA_USER_ID": "your-id",
        "HABITICA_API_TOKEN": "your-token",
        "MCP_LANG": "en"  // or zh-CN
      }
    }
  }
}

対話の例

User: "Create a habit for learning Python"
AI:   "Sure, the habit has been created!"

User: "Show me today's tasks"
AI:   "Here is your task list for today…"

User: "Add a checklist item to my project task: 'Review code'"
AI:   "Added checklist item 'Review code' to your project task!"

User: "I finished my workout, please record it"
AI:   "Great job! The workout is logged."

🛠️ 利用可能なツール

ユーザー関連

• get_user_profile：ユーザープロフィール情報を取得します
• get_stats：ユーザーの統計情報を取得します
• get_inventory：インベントリの一覧を取得します

タスク管理

• get_tasks：タスクの一覧を取得します（習慣、デイリー、ToDo、報酬を指定できます）
• create_task：新しいタスクを作成します
• update_task：タスクを更新します
• delete_task：タスクを削除します
• score_task：タスクを完了するか、習慣を記録します

チェックリスト管理

• get_task_checklist：タスクのチェックリスト項目を取得します
• add_checklist_item：タスクにチェックリスト項目を追加します
• update_checklist_item：チェックリスト項目を更新します
• delete_checklist_item：チェックリスト項目を削除します
• score_checklist_item：チェックリスト項目のスコアを記録します（完了／未完了に設定）

タグ管理

• get_tags：タグの一覧を取得します
• create_tag：新しいタグを作成します

ペットとマウント

• get_pets：ペットの一覧を取得します
• feed_pet：ペットに餌を与えます
• hatch_pet：ペットを孵化させます
• get_mounts：マウントの一覧を取得します
• equip_item：ペット、マウント、または装備を装備します

ショップと購入

• get_shop：ショップアイテムの一覧を取得します
• buy_item：ショップアイテムを購入します
• buy_reward：報酬を購入します

通知管理

• get_notifications：通知の一覧を取得します
• read_notification：通知を既読にします

スキルシステム

• cast_spell：呪文を唱えます

📖 API の使用例

タスクを作成する

{
  "type": "todo",
  "text": "Complete project documentation",
  "notes": "Including API docs and user guide",
  "difficulty": 1.5,
  "priority": 2,
  "checklist": [
    {"text": "Write API documentation", "completed": false},
    {"text": "Create user guide", "completed": false},
    {"text": "Review and proofread", "completed": false}
  ]
}

タスクを完了する

{
  "taskId": "task-id-here",
  "direction": "up"
}

特定の種類のタスクを取得する

{
  "type": "todos"
}

ペットを管理する

{
  "pet": "Wolf-Base",
  "food": "Meat"
}

アイテムを購入する

{
  "itemKey": "armor_warrior_1",
  "quantity": 1
}

チェックリストを管理する

// Add checklist item
{
  "taskId": "task-id-here",
  "text": "Research requirements"
}

// Update checklist item
{
  "taskId": "task-id-here",
  "itemId": "checklist-item-id",
  "text": "Updated item text",
  "completed": true
}

// Score checklist item (toggle completion)
{
  "taskId": "task-id-here",
  "itemId": "checklist-item-id"
}

タスクの種類

• habit：習慣（プラスまたはマイナスの記録が可能）
• daily：デイリータスク（毎日リセットされます）
• todo：ToDo 項目（一度限りのタスク）
• reward：報酬（ゴールドで購入できます）

難易度

• 0.1：簡単
• 1：普通
• 1.5：難しい
• 2：非常に難しい

優先度

• 0.1：低
• 1：中
• 1.5：高
• 2：最高

🔧 トラブルシューティング

よくある問題

問題：サーバーの起動に失敗しました

Solution: 
1. Check Node.js version is 18+
2. Confirm environment variables are set correctly
3. Verify API credentials are valid

問題：API 呼び出しに失敗しました

Solution:
1. Check network connection
2. Verify Habitica API credentials
3. Confirm API rate limits haven't been exceeded

問題：タスクまたはペットが見つかりません

Solution:
1. Confirm task ID is correct
2. Check if task exists in Habitica
3. Verify user permissions

デバッグモード

# Enable verbose logging
DEBUG=* npm start

ヘルプ

• 📚 Habitica API のドキュメントを確認してください
• 🐛 Issuesを送信してください

🤝 コントリビューション

あらゆる形でのコントリビューションを歓迎します！

コントリビューション方法

1. このプロジェクトをフォークします
2. 機能ブランチを作成します（git checkout -b feature/AmazingFeature）
3. 変更をコミットします（git commit -m 'Add some AmazingFeature'）
4. ブランチにプッシュします（git push origin feature/AmazingFeature）
5. プルリクエストを作成します

開発ガイドライン

• 既存のコードスタイルに従ってください
• 適切なテストを追加してください
• 関連するドキュメントを更新してください
• すべてのテストが合格することを確認してください

📄 ライセンス

このプロジェクトは MIT ライセンスのオープンソースです。詳細は LICENSE ファイルをご覧ください。

🌟 謝辞

• 優れた API を提供してくださった Habitica に感謝します
• MCP プロトコルを提供してくださった Anthropic に感謝します
• ご支援くださったすべてのコントリビューターとユーザーに感謝します

---