# Habitica MCP Server 🧙‍♂️⚔️

Servidor **Model Context Protocol (MCP)** completo para **Habitica**, desarrollado con Python y **FastMCP**.

Permite a cualquier modelo de Inteligencia Artificial (Claude Desktop, Gemini CLI, Antigravity, Cursor) interactuar de forma nativa con todo el ecosistema de Habitica: **autenticación directa sin tokens manuales**, **gestión de tareas**, **equipos y misiones**, **chat**, **personaje**, **inventario**, **mascotas** y **desafíos**.

---

## 🌟 Características Principales

* 🔑 **Login sin Tokens Manuales:** Puedes iniciar sesión directamente con tu usuario/email y contraseña usando la ventana interactiva (`login_window.py`) o la herramienta MCP `habitica_login`. Las credenciales se conservan de forma segura y local en `.habitica_session.json` (ignorado por Git).
* 👥 **Gestión Integral de Equipos (Party & Guilds):** Consulta detalles, roster con niveles y clases, auditoría de inactividad (`get_party_activity_summary`), reclutamiento y expulsión de miembros inactivos (`remove_group_member`).
* 🐉 **Misiones de Equipo (Quests):** Convoca misiones con pergaminos, acéptalas, recházalas o cancélalas.
* 💬 **Chat Integrado:** Lee los chats de equipo/gremios en tiempo real, envía mensajes y da "likes".
* ⚔️ **Gestión de Tareas y Hábitos:** CRUD completo de hábitos (+/-), diarias, to-dos y recompensas con dificultad configurable. ¡Puntúa tareas (`score_task`) para ganar oro, EXP y golpear al jefe!
* 🧙‍♂️ **Personaje y Progresión:** Consulta vida, maná, oro, racha y clase. Lanza hechizos, duerme en la Posada (pausar daño diario) y asigna puntos de atributo ganados al subir nivel.
* 🎒 **Inventario y Mercado:** Equipa armaduras/armas de combate o de disfraz (`costume`), compra pociones y pergaminos.
* 🐾 **Mascotas y Monturas:** Eclosiona huevos con pociones y alimenta a tus criaturas.
* 🏷️ **Etiquetas (Tags):** Crea, edita y asocia tags a tareas.
* 🏆 **Desafíos (Challenges):** Crea retos para tu party con premios en gemas, agrega tareas al reto, únete, abandona y corona al ganador (`select_challenge_winner`).

---

## 📋 Requisitos Previos

* **Python 3.10** o superior (probado en Python 3.10 - 3.14).
* Gestor de paquetes `pip` o `uv`.

---

## 🚀 Instalación Paso a Paso

### 1. Clonar el Repositorio
```bash
git clone https://github.com/TU_USUARIO/habitica-mcp.git
cd habitica-mcp
```

### 2. Crear un Entorno Virtual (Opcional pero recomendado)
```bash
# Con Python estándar
python -m venv .venv
# En Windows:
.venv\Scripts\activate
# En Linux/macOS:
source .venv/bin/activate
```

### 3. Instalar Dependencias
Instala el paquete en modo editable con pip:
```bash
pip install -e .
```
*(O si usas `uv`: `uv sync`)*

---

## 🔐 Autenticación (Cómo Iniciar Sesión)

Dispones de **dos opciones**:

### Opción A: Interfaz Gráfica o Consola (Recomendada)
No necesitas copiar ni pegar manualmente tu `User ID` ni tu `API Token`. Simplemente ejecuta:

* **Ventana visual (GUI nativa):**
  ```bash
  python login_window.py
  ```
* **En consola / terminal:**
  ```bash
  python login.py
  ```

Ingresa tu usuario (o correo) y contraseña. El script se conectará a Habitica, obtendrá tus identificadores de sesión y los guardará localmente en `.habitica_session.json`.

### Opción B: Variables de Entorno (`.env`)
Si prefieres usar tus API Tokens directamente:
1. Copia `.env.example` a `.env`:
   ```bash
   cp .env.example .env
   ```
2. Completa tus credenciales (disponibles en Habitica en *Configuración > API*):
   ```env
   HABITICA_USER_ID=tu-user-id-uuid
   HABITICA_API_TOKEN=tu-api-token
   HABITICA_CLIENT_NAME=HabiticaMCP
   ```

---

## ⚙️ Configuración en Clientes MCP

### En Claude Desktop (`claude_desktop_config.json`)
Añade lo siguiente a tu archivo de configuración de Claude Desktop:

```json
{
  "mcpServers": {
    "habitica": {
      "command": "python",
      "args": [
        "-m",
        "habitica.server"
      ],
      "cwd": "/ruta/absoluta/a/habitica-mcp"
    }
  }
}
```
*(En Windows usa doble barra invertida en la ruta, ej: `D:\\proyectos\\habitica-mcp`)*.

### En Gemini CLI / Antigravity (`mcp_config.json`)
```json
{
  "mcpServers": {
    "habitica": {
      "command": "python",
      "args": [
        "-m",
        "habitica.server"
      ],
      "cwd": "D:\\PERSONAL\\PRACTICAS\\PROGRAMACIÓN\\MCP-ANTIGRAVITY\\habitica-mcp"
    }
  }
}
```

---

## 🛠️ Catálogo Completo de Herramientas (59 Tools)

<details>
<summary><b>1. Autenticación (3 tools)</b></summary>

* `habitica_login(username_or_email, password)`: Login directo con usuario y contraseña.
* `habitica_auth_status()`: Estado actual de la conexión.
* `habitica_logout()`: Cierra sesión y elimina credenciales locales.
</details>

<details>
<summary><b>2. Equipos y Gremios (11 tools)</b></summary>

* `get_groups(group_types)`: Lista grupos del usuario.
* `get_group_details(group_id)`: Detalles del equipo/gremio.
* `get_group_members(group_id, include_all_public_fields)`: Lista completa de integrantes con estadísticas.
* `get_party_activity_summary(group_id)`: Resumen de actividad y tiempo de inactividad de los miembros.
* `invite_to_group(group_id, uuids, emails)`: Invitar miembros por ID o correo.
* `remove_group_member(member_id, group_id, message)`: Expulsar miembros (solo líder).
* `create_group(name, group_type, privacy, description)`: Crear gremio o equipo.
* `update_group(group_id, name, description, leader_message)`: Actualizar ajustes de grupo.
* `join_group(group_id)`: Unirse a un grupo.
* `leave_group(group_id, keep_challenges)`: Salir de un grupo.
* `reject_group_invite(group_id)`: Rechazar invitación.
</details>

<details>
<summary><b>3. Misiones de Equipo / Quests (5 tools)</b></summary>

* `quest_invite(quest_key)`: Iniciar misión con pergamino.
* `quest_accept()`: Aceptar misión activa.
* `quest_reject()`: Rechazar misión.
* `quest_abort()`: Cancelar misión en curso (líder).
* `quest_leave()`: Abandonar misión individualmente.
</details>

<details>
<summary><b>4. Chat de Equipo (4 tools)</b></summary>

* `get_group_chat(group_id)`: Leer últimos mensajes.
* `send_group_chat(message, group_id)`: Publicar en el chat.
* `like_chat_message(chat_id, group_id)`: Dar like a un mensaje.
* `mark_chat_seen(group_id)`: Marcar chat como leído.
</details>

<details>
<summary><b>5. Tareas y Hábitos (7 tools)</b></summary>

* `get_tasks(task_type)`: Listar hábitos, diarias, to-dos o recompensas.
* `get_task(task_id)`: Detalles de una tarea específica.
* `create_task(text, task_type, notes, priority, up, down, due_date, tags)`: Crear nueva tarea.
* `update_task(task_id, text, notes, priority)`: Modificar tarea.
* `delete_task(task_id)`: Borrar tarea.
* `score_task(task_id, direction)`: Puntuar tarea (`up`/`down`).
* `unlink_all_challenge_tasks(keep)`: Desvincular tareas de retos.
</details>

<details>
<summary><b>6. Personaje y Progresión (6 tools)</b></summary>

* `get_user_profile(user_fields)`: Estadísticas completas (HP, MP, EXP, GP, nivel, clase).
* `get_anonymized_profile()`: Datos públicos del personaje.
* `toggle_sleep()`: Pausar/reanudar daño durmiendo en la Posada.
* `cast_spell(spell_id, target_id)`: Lanzar habilidades de clase.
* `allocate_stat_point(stat)`: Asignar puntos a atributos (`str`, `con`, `int`, `per`).
* `trigger_cron()`: Procesar cambio de día manualmente.
</details>

<details>
<summary><b>7. Inventario y Mercado (3 tools)</b></summary>

* `equip_item(item_key, slot_type)`: Equipar equipo de combate (`equipped`) o cosmético (`costume`).
* `buy_item(item_key)`: Comprar pociones o equipo en la tienda con oro.
* `get_buy_inventory()`: Catálogo de ítems en venta.
</details>

<details>
<summary><b>8. Mascotas y Monturas (2 tools)</b></summary>

* `hatch_pet(egg, hatching_potion)`: Eclosionar huevos con pociones.
* `feed_pet(pet, food)`: Alimentar mascotas para convertirlas en monturas.
</details>

<details>
<summary><b>9. Etiquetas / Tags (6 tools)</b></summary>

* `get_tags()`: Listar etiquetas.
* `create_tag(name)`: Crear etiqueta.
* `update_tag(tag_id, name)`: Renombrar etiqueta.
* `delete_tag(tag_id)`: Eliminar etiqueta.
* `tag_task(task_id, tag_id)`: Asignar etiqueta a tarea.
* `untag_task(task_id, tag_id)`: Quitar etiqueta.
</details>

<details>
<summary><b>10. Desafíos / Challenges (12 tools)</b></summary>

* `get_my_challenges(page)`: Desafíos activos o disponibles.
* `get_party_challenges(group_id)`: Desafíos de tu equipo.
* `get_challenge_details(challenge_id)`: Ver reglas y participantes.
* `get_challenge_tasks(challenge_id)`: Tareas asignadas al reto.
* `create_challenge(name, short_name, description, summary, group_id, prize)`: Crear nuevo desafío.
* `add_task_to_challenge(challenge_id, text, task_type, notes, priority, up, down)`: Agregar tareas al reto.
* `update_challenge(challenge_id, name, description, summary)`: Editar desafío.
* `clone_challenge(challenge_id)`: Duplicar reto existente.
* `delete_challenge(challenge_id)`: Borrar reto y reembolsar premio.
* `join_challenge(challenge_id)`: Unirse al desafío.
* `leave_challenge(challenge_id, keep)`: Salir del reto.
* `select_challenge_winner(challenge_id, winner_id)`: Elegir ganador y transferir premio.
</details>

---

## 🔒 Seguridad y Privacidad

* Este repositorio **no almacena contraseñas ni tokens**.
* El archivo de sesión `.habitica_session.json` y los archivos `.env` están protegidos e incluidos en el `.gitignore`.
* Toda la comunicación con los servidores de Habitica se realiza exclusivamente mediante HTTPS (`https://habitica.com/api/v3`).

---

## 📄 Licencia

Distribuido bajo la Licencia MIT. Consulta el archivo `LICENSE` para más detalles.