Habitica MCP Server

Habitica MCP服务器

_中文文档请阅读 README.zh-CN.md_

一个模型上下文协议（MCP）服务器，让人工智能助手与Habitica API无缝交互——创建任务、跟踪习惯、饲养宠物并享受游戏化的生产力。

✨ 特性

🎮 核心游戏功能

• 📋 智能任务管理 –创建/查看/更新/删除所有任务类型
• ✅ 检查表管理 –在任务中添加、更新、删除和评分清单项目
• 🎯 习惯追踪 –记录习惯完成情况并建立健康的日常生活
• 🐾 宠物饲养 –孵化和喂养宠物，看着它们成长
• 🏇 收藏山 –管理和装备各种支架
• 🛍️ 购物与奖励 –浏览和购买游戏内物品
• ⚡ 技能体系 –铸造类技能，以提高游戏性

📊 面向数据的功能

• 👤 用户档案 –获取详细的用户信息和统计数据
• 🏷️ 标签管理 –创建和管理标签以实现更好的组织
• 📬 通知中心 –读取和管理系统通知
• 📦 库存 –列出您拥有的每一件物品和设备

🤖 AI集成亮点

• 🧠 自然语言控制 –通过对话操作Habitica
• 📝 任务建议 –AI可以按需创建任务
• 📈 进度报告 –自动跟踪和总结进度
• 🎨 个性化体验 –根据您的习惯量身定制的建议

🚀 快速开始

先决条件

• Node.js 18+
• npm或纱线
• 有效的Habitica帐户

安装

1. 克隆仓库

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

1. 安装依赖项

npm install

1. 设置API凭据 （见下一节）

1. 启动服务器

npm start

⚙️ 配置

获取Habitica API证书

1. 登录到 Habitica
2. 点击您的头像→ 设置
3. 打开 API 标签
4. 复制 用户ID 和 API代币

环境变量

方法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桌面配置示例：

{
  "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：获取任务列表（可以指定类型：习惯、日常、待办事项、奖励）
• 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：待办事项（一次性任务）
• 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文档
• 🐛 提交 问题

🤝 贡献

我们欢迎各种形式的捐款！

如何做出贡献

1. 分叉此项目
2. 创建特征分支(git checkout -b feature/AmazingFeature)
3. 提交更改(git commit -m 'Add some AmazingFeature')
4. 推送到分支(git push origin feature/AmazingFeature)
5. 创建拉取请求

开发指南

• 遵循现有代码样式
• 添加适当的测试
• 更新相关文件
• 确保所有测试通过

📄 许可证

此项目是MIT许可证下的开源项目-请参阅 许可证 文件以获取详细信息。

🌟 致谢

• 多亏了 Habitica 提供卓越的API
• 多亏了 Anthropic 对于MCP协议
• 感谢所有贡献者和用户的支持

______________________________________________________________________

Let AI become your Habitica task management assistant!