habitica-mcp

Habitica Model Context Protocol server built with Effect v4 beta.

The server exposes typed Habitica read/write tools over stdio, with an opt-in Streamable HTTP transport. Tool handlers depend on an Effect HabiticaGateway port; the live adapter uses Effect HTTP and schema-decodes Habitica API responses at the boundary.

Requirements

• Node.js >=22.12.0

• pnpm >=10

This repo uses pnpm rather than bun because the server runs on Node stdio, the lockfile is already deterministic, and the Effect MCP docs target Node runtime primitives.

Related MCP server: Basic MCP Server

Install

pnpm add -g habitica-mcp@alpha

For local development:

pnpm install

Required variables:

• HABITICA_USER_ID

• HABITICA_API_TOKEN

• HABITICA_CLIENT_ID

• HABITICA_API_BASE_URL defaults to https://habitica.com/api/v3

For a local checkout, copy the example env file and fill in your Habitica credentials:

cp .env.example .env

Commands

pnpm dev                    # run the stdio MCP server from TypeScript
pnpm dev:http               # run the Streamable HTTP server from TypeScript
pnpm build                  # emit dist
pnpm check                  # every gate, mutation included
pnpm check:without-mutation # every gate except mutation
pnpm test                   # run unit tests
pnpm test:coverage          # run unit tests with 100% coverage thresholds
pnpm e2e                    # run strict effect-bdd Gherkin tests
pnpm mutation               # Stryker at 100%, then report health and baselines
pnpm mutation:dev           # incremental Stryker run for local iteration
pnpm lint                   # policy scripts, dep graph, rule tests, oxlint, knip

pnpm e2e is a deterministic fake-gateway suite. It exercises the full MCP tool handler surface without live Habitica credentials or network calls.

pnpm test includes a protocol suite that speaks real JSON-RPC to the real server layer. It swaps the process streams for in-memory ones with Stdio.layerTest, then drives initialize, tools/list, tools/call, resources/list, resources/read, resources/templates/list, prompts/list, prompts/get, and completion/complete. Nothing about the MCP wiring is stubbed, so a registration that never reaches the protocol fails there rather than passing an in-memory assertion. A second suite mounts the same layer over HTTP on an ephemeral port to confirm both transports report the same identity.

Feedback Ladder

Run the smallest relevant command while developing, then widen:

1. pnpm test

2. pnpm test:coverage

3. pnpm e2e

4. pnpm lint

5. pnpm build

6. pnpm check:without-mutation

7. pnpm mutation

8. pnpm check

Deterministic Gate

pnpm check is pnpm check:without-mutation followed by pnpm mutation.

pnpm check:without-mutation runs build, typecheck (source and policy scripts), pnpm lint, format check, 100% unit coverage, and the strict effect-bdd Gherkin e2e suite.

pnpm lint runs, in order:

• lint:policy — the deterministic policy scripts in scripts/, covering suppression comments, repository-relative paths, no-op scripts, .cursor/rules health, version pinning, policy-exception health, mutation scope, Stryker config, and coverage config.

• lint:deps — dependency-cruiser architectural boundaries.

• lint:custom-rule-tests — every custom oxlint rule has RuleTester coverage, then runs those rule tests.

• lint:oxlint — type-aware oxlint with complexity: 4 and the custom habitica-mcp plugin.

• lint:knip — unused files, dependencies, and exports.

pnpm mutation runs Stryker at a 100% break threshold, then lint:mutation-report-health (no survivors, no uncovered mutants) and lint:mutation-baselines (a ratchet that only moves down, and a mutant-count floor so the mutate scope cannot quietly shrink).

Coverage and Mutation Scope

Coverage and mutation both start from all of src/**/*.ts. Narrowing is only possible through a named exception in scripts/policy-exceptions.ts that carries a rationale, a removal condition, and an owning policy script. lint-coverage-policy and lint-mutation-scope fail if vitest.config.ts or stryker.config.json excludes a path that no exception covers, and also if an exception goes stale.

Lefthook runs pnpm check on pre-commit:

pnpm prepare

GitHub Actions splits the same work into two jobs: gates runs check:without-mutation, and mutation runs Stryker incrementally on pull requests and in full on pushes to main and on a nightly schedule.

Tool Surface

Core tools cover profile, stats, tasks, tags, checklists, and notifications. Expanded tools cover rewards, inventory, shop items, pets, mounts, and skills.

Every tool talks to Habitica, so the credential-free connection check is reading the habitica-mcp://capabilities resource rather than calling a tool.

All 30 tool names are namespaced lower snake_case, so they stay distinguishable when a client has several MCP servers connected. Every tool also carries a human-readable title for approval dialogs, a description, and a full set of MCP behaviour hints:

Mutating tools name their verb explicitly, as in habitica_create_task, habitica_delete_task, habitica_score_task, and habitica_cast_skill. They request approval and return typed structured results. Read tools are idempotent; creates, purchases, casts, and toggles are not, because repeating them spends gold, mana, or inventory.

Every tool parameter carries a description, since those strings are the only signal the model has when choosing arguments.

Prompts and Resources

Three prompts are registered with snake_case identifiers and completions for their arguments: habitica_daily_planning, habitica_task_review, and habitica_habit_check_in.

Two static resources describe the server itself:

• habitica-mcp://capabilities (markdown)

• habitica-mcp://task-template (JSON)

One resource template exposes individual tasks so a client can attach a single task as context instead of pulling the whole list through a tool call:

• habitica://task/{taskId}, with completion over the current task ids

Transports

Both transports mount the same capability layer, so they cannot advertise different tools.

• stdio (habitica-mcp) is the default and what MCP clients expect.

• Streamable HTTP (habitica-mcp-http) serves MCP at POST /mcp.

The HTTP transport binds 127.0.0.1:3000 by default and performs no authentication of its own. It carries live Habitica credentials, so only change HABITICA_MCP_HTTP_HOST if you are putting an authenticating proxy in front of it.

• HABITICA_MCP_HTTP_HOST defaults to 127.0.0.1

• HABITICA_MCP_HTTP_PORT defaults to 3000

Architecture Guardrails

• MCP stdout is protocol-owned; logs go to stderr.

• Tools import HabiticaGateway, not HabiticaHttpAdapter or raw route strings. Resource templates may read through the same port.

• Habitica credentials and auth headers must never be logged.

• Every Tool.make call declares a success schema.

• The server reports its version from package.json, so what a client sees on initialize cannot drift from what was published.

• Deterministic modules must be listed in coverage and mutation scope. The only exclusions are src/main.ts and src/mainHttp.ts, which bind a transport and launch; anything decidable belongs above them.

MCP Config

Use the local TypeScript entrypoint while developing:

{
  "mcpServers": {
    "habitica": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/habitica-mcp", "dev"]
    }
  }
}

After pnpm build, use the package binary:

{
  "mcpServers": {
    "habitica": {
      "command": "node",
      "args": ["/absolute/path/to/habitica-mcp/dist/main.js"]
    }
  }
}

After installing from npm, use the binary:

{
  "mcpServers": {
    "habitica": {
      "command": "habitica-mcp"
    }
  }
}

Publishing

This package is intentionally pre-1.0. Publish early builds with the manual Publish GitHub Actions workflow. It uses the repository NPM_TOKEN secret, runs pnpm check, and publishes with npm provenance on the alpha dist-tag.

Equivalent local command:

pnpm check
npm publish --tag alpha --provenance

prepack builds dist/; publishConfig marks the package public and enables npm provenance.