Habitica MCP

Servidor MCP em TypeScript para gerenciar o Habitica como camada de execução diária — não como gerenciador de projeto.

Agentes consultam e (com confirmação explícita) alteram hábitos, diárias, afazeres e recompensas via API do Habitica. Planejamento de projeto, backlog e histórico permanecem em ferramentas externas (Obsidian, GitHub Issues, Azure Boards, Jira, etc.).

Status

MVP amplo implementado (Sprints 1–12). Incremento 8 entregue (CRUD hábitos/diárias, update de afazer, remoção tipada). Incremento 7 (Workers) adiado.

Stack

• Node.js + TypeScript

• @modelcontextprotocol/sdk

• Transporte stdio

• Gerenciador de pacotes pnpm

• Plugins: plugins/habitica-rpg-codex e plugins/habitica-rpg-cursor

Fronteira do produto

• Habitica = compromisso pessoal e rotina do dia.

• MCP = ponte segura para agentes (leitura primeiro; escrita só com confirm: true).

• Não importar backlog completo de projeto para o Habitica.

Detalhes: CONTEXT.md.

Segurança

• Credenciais apenas em variáveis de ambiente (fora do repositório). Use .env local (gitignored) a partir de .env.example.

• Nunca registrar tokens, cookies, Authorization, payloads sensíveis ou credenciais em notas, logs, exemplos ou testes.

• Variáveis: HABITICA_USER_ID, HABITICA_API_TOKEN, HABITICA_X_CLIENT.

• Política de reporte: SECURITY.md.

Quick start

pnpm install
cp .env.example .env   # preencha as três variáveis (sem commitar)
pnpm run build
pnpm start             # ou: pnpm dev
pnpm check             # typecheck + lint + format + test

Smoke: pnpm exec tsx scripts/smoke-list.ts

Configuração MCP (stdio)

{
  "mcpServers": {
    "habitica": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "<caminho-do-repo>",
      "env": {
        "HABITICA_USER_ID": "<seu-user-id>",
        "HABITICA_API_TOKEN": "<seu-api-token>",
        "HABITICA_X_CLIENT": "<user-id>-habitica-mcp"
      }
    }
  }
}

Tools

Escrita / pontuação / remoção exigem confirm: true (sem confirm = preview).

Contribuindo

• CONTRIBUTING.md — setup, PRs e escopo

• CODE_OF_CONDUCT.md — padrões de comunidade

• SECURITY.md — vulnerabilidades (reporte privado)

• LICENSE — MIT

Documentação