# Habitica MCP Server

_中文文档请阅读 **[README.zh-CN.md](README.zh-CN.md)**_

A Model Context Protocol (MCP) server that lets AI assistants seamlessly interact with the Habitica API – create tasks, track habits, raise pets and enjoy gamified productivity.

## ✨ Features

### 🎮 Core Gameplay Features
- 📋 **Smart task management** – create / view / update / delete all task types
- ✅ **Checklist management** – add, update, delete and score checklist items within tasks
- 🎯 **Habit tracking** – record habit completions and build healthy routines
- 🐾 **Pet raising** – hatch and feed pets, watch them grow
- 🏇 **Mount collection** – manage and equip all kinds of mounts
- 🛍️ **Shop & rewards** – browse and buy in-game items
- ⚡ **Skill system** – cast class skills to enhance gameplay

### 📊 Data-oriented Features
- 👤 **User profile** – fetch detailed user information and stats
- 🏷️ **Tag management** – create and manage tags for better organisation
- 📬 **Notification centre** – read and manage system notifications
- 📦 **Inventory** – list every item and piece of equipment you own

### 🤖 AI Integration Highlights
- 🧠 **Natural-language control** – operate Habitica via conversation
- 📝 **Task suggestions** – AI can create tasks on demand
- 📈 **Progress reporting** – automatically track and summarise progress
- 🎨 **Personalised experience** – tailored recommendations based on your habits

## 🚀 Quick Start

### Prerequisites
- Node.js 18+
- npm or yarn
- A valid Habitica account

### Installation

1. **Clone the repo**
```bash
git clone https://github.com/ibreaker/habitica-mcp-server.git
cd habitica-mcp-server
```

2. **Install dependencies**
```bash
npm install
```

3. **Set API credentials** (see next section)

4. **Start the server**
```bash
npm start
```

## ⚙️ Configuration

### Get Habitica API credentials
1. Log into [Habitica](https://habitica.com)
2. Click your avatar → **Settings**
3. Open the **API** tab
4. Copy **User ID** and **API Token**

### Environment variables

**Method A: export variables**
```bash
export HABITICA_USER_ID="your-user-id"
export HABITICA_API_TOKEN="your-api-token"
```

**Method B: .env file**
```bash
HABITICA_USER_ID=your-user-id
HABITICA_API_TOKEN=your-api-token
```

> ⚠️ **Security tip:** never commit your API keys to version control.

## 🎯 Usage

### Start the server
```bash
# Production
npm start

# Development (with reload)
npm run dev
```

### MCP client integration

The server follows the MCP spec and works with any AI client that supports MCP. Example Claude Desktop config:
```json
{
  "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
      }
    }
  }
}
```

### Example dialogue
```
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."
```

## 🛠️ Available Tools

### User Related
- `get_user_profile`: Get user profile information
- `get_stats`: Get user statistics
- `get_inventory`: Get inventory list

### Task Management
- `get_tasks`: Get task list (can specify type: habits, dailys, todos, rewards)
- `create_task`: Create new task
- `update_task`: Update task
- `delete_task`: Delete task
- `score_task`: Complete task or record habit

### Checklist Management
- `get_task_checklist`: Get checklist items for a task
- `add_checklist_item`: Add checklist item to task
- `update_checklist_item`: Update checklist item
- `delete_checklist_item`: Delete checklist item
- `score_checklist_item`: Score checklist item (mark complete/incomplete)

### Tag Management
- `get_tags`: Get tag list
- `create_tag`: Create new tag

### Pets and Mounts
- `get_pets`: Get pet list
- `feed_pet`: Feed pet
- `hatch_pet`: Hatch pet
- `get_mounts`: Get mount list
- `equip_item`: Equip pet, mount or equipment

### Shop and Purchases
- `get_shop`: Get shop item list
- `buy_item`: Buy shop item
- `buy_reward`: Buy reward

### Notification Management
- `get_notifications`: Get notification list
- `read_notification`: Mark notification as read

### Skill System
- `cast_spell`: Cast spell

## 📖 API Usage Examples

### Create Task
```json
{
  "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}
  ]
}
```

### Complete Task
```json
{
  "taskId": "task-id-here",
  "direction": "up"
}
```

### Get Specific Task Type
```json
{
  "type": "todos"
}
```

### Pet Management
```json
{
  "pet": "Wolf-Base",
  "food": "Meat"
}
```

### Buy Item
```json
{
  "itemKey": "armor_warrior_1",
  "quantity": 1
}
```

### Checklist Management
```json
// 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"
}
```

## Task Types

- `habit`: Habit (can be recorded positively or negatively)
- `daily`: Daily task (resets every day)
- `todo`: To-do item (one-time task)
- `reward`: Reward (can be purchased with gold)

## Difficulty Levels

- `0.1`: Easy
- `1`: Medium
- `1.5`: Hard
- `2`: Extreme

## Priority Levels

- `0.1`: Low
- `1`: Medium
- `1.5`: High
- `2`: Extreme

## 🔧 Troubleshooting

### Common Issues

**Issue**: Server startup failed
```
Solution: 
1. Check Node.js version is 18+
2. Confirm environment variables are set correctly
3. Verify API credentials are valid
```

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

**Issue**: Task or pet not found
```
Solution:
1. Confirm task ID is correct
2. Check if task exists in Habitica
3. Verify user permissions
```

### Debug Mode
```bash
# Enable verbose logging
DEBUG=* npm start
```

### Get Help
- 📚 Check [Habitica API Documentation](https://habitica.com/apidoc/)
- 🐛 Submit [Issues](https://github.com/ibreaker/habitica-mcp-server/issues)

## 🤝 Contributing

We welcome all forms of contributions!

### How to Contribute
1. Fork this project
2. Create feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to branch (`git push origin feature/AmazingFeature`)
5. Create Pull Request

### Development Guidelines
- Follow existing code style
- Add appropriate tests
- Update relevant documentation
- Ensure all tests pass

## 📄 License

This project is open source under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🌟 Acknowledgments

- Thanks to [Habitica](https://habitica.com) for providing an excellent API
- Thanks to [Anthropic](https://anthropic.com) for the MCP protocol
- Thanks to all contributors and users for their support

---

<div align="center">
  <b>Let AI become your Habitica task management assistant!</b>
</div>