habitica-mcp 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,146 @@
+# habitica-mcp
+
+Habitica Model Context Protocol server built with Effect v4 beta.
+
+The server exposes typed Habitica read/write tools over stdio. 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.
+
+## Install
+
+```sh
+pnpm add -g habitica-mcp@alpha
+```
+
+For local development:
+
+```sh
+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:
+
+```sh
+cp .env.example .env
+```
+
+## Commands
+
+```sh
+pnpm dev          # run the stdio MCP server from TypeScript
+pnpm build        # emit dist
+pnpm check        # full deterministic gate used by Lefthook
+pnpm test         # run unit tests
+pnpm test:coverage # run unit tests with 100% coverage threshold
+pnpm e2e          # run strict effect-bdd Gherkin tests
+pnpm mutation     # run Stryker with 100% mutation threshold
+```
+
+## Deterministic Gate
+
+`pnpm check` runs build, typecheck, suppression policy, deterministic scope
+policy, custom oxlint RuleTester coverage, oxlint, format check, 100% unit
+coverage, strict `effect-bdd` Gherkin e2e, 100% Stryker mutation coverage for
+the deterministic core, and `knip`.
+
+Lefthook runs `pnpm check` on pre-commit:
+
+```sh
+pnpm prepare
+```
+
+GitHub Actions runs the same `pnpm check` gate on pushes to `main` and pull
+requests.
+
+## Tool Surface
+
+`HelloWorldTool` returns a deterministic greeting and does not require Habitica
+credentials. Use it as the first MCP smoke test.
+
+Core tools cover profile, stats, tasks, tags, checklists, and notifications.
+Expanded tools cover rewards, inventory, shop items, pets, mounts, and skills.
+
+Mutating tools use explicit verb names such as `CreateTaskTool`,
+`UpdateTaskTool`, `DeleteTaskTool`, `ScoreTaskTool`, `ReadNotificationTool`,
+`BuyRewardTool`, and `CastSkillTool`. They request approval and return typed
+structured results.
+
+## Architecture Guardrails
+
+- MCP stdout is protocol-owned; logs go to stderr.
+- Tools import `HabiticaGateway`, not `HabiticaHttpAdapter` or raw route
+  strings.
+- Habitica credentials and auth headers must never be logged.
+- Every `Tool.make` call declares a success schema.
+- Deterministic modules must be listed in coverage and mutation scope.
+
+## MCP Config
+
+Use the local TypeScript entrypoint while developing:
+
+```json
+{
+  "mcpServers": {
+    "habitica": {
+      "command": "pnpm",
+      "args": ["--dir", "/absolute/path/to/habitica-mcp", "dev"]
+    }
+  }
+}
+```
+
+After `pnpm build`, use the package binary:
+
+```json
+{
+  "mcpServers": {
+    "habitica": {
+      "command": "node",
+      "args": ["/absolute/path/to/habitica-mcp/dist/main.js"]
+    }
+  }
+}
+```
+
+After installing from npm, use the binary:
+
+```json
+{
+  "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:
+
+```sh
+pnpm check
+npm publish --tag alpha --provenance
+```
+
+`prepack` builds `dist/`; `publishConfig` marks the package public and enables npm provenance.

package/dist/HabiticaMcp.d.ts

@@ -0,0 +1 @@
+export declare const run: () => void;

package/dist/HabiticaMcp.js

@@ -0,0 +1,17 @@
+import { NodeRuntime, NodeStdio } from "@effect/platform-node";
+import { Layer, Logger } from "effect";
+import { McpServer } from "effect/unstable/ai";
+import { HabiticaConfig } from "./config/HabiticaConfig.js";
+import { HabiticaHttpAdapter } from "./habitica/HabiticaHttpAdapter.js";
+import { DailyPlanningPrompt, HabitCheckInPrompt, TaskReviewPrompt, } from "./prompts/HabiticaPrompts.js";
+import { CapabilitiesResource, TaskTemplateResource } from "./resources/HabiticaResources.js";
+import { HabiticaToolLayer, HabiticaToolkit } from "./tools/HabiticaTools.js";
+const HabiticaToolkitLayer = McpServer.toolkit(HabiticaToolkit).pipe(Layer.provideMerge(HabiticaToolLayer.pipe(Layer.provide(HabiticaHttpAdapter.gatewayLayer), Layer.provide(HabiticaConfig.layer))));
+const HabiticaMcpPartsLayer = Layer.mergeAll(CapabilitiesResource, TaskTemplateResource, DailyPlanningPrompt, HabitCheckInPrompt, TaskReviewPrompt, HabiticaToolkitLayer);
+const ServerLayer = HabiticaMcpPartsLayer.pipe(Layer.provide(McpServer.layerStdio({
+    name: "Habitica MCP",
+    version: "0.0.1-alpha.0",
+})), Layer.provide(NodeStdio.layer), Layer.provide(Layer.succeed(Logger.LogToStderr)(true)));
+export const run = () => {
+    Layer.launch(ServerLayer).pipe(NodeRuntime.runMain);
+};

package/dist/config/HabiticaConfig.d.ts

@@ -0,0 +1,13 @@
+import { Config, Context, Layer } from "effect";
+export interface HabiticaConfigShape {
+    readonly apiBaseUrl: string;
+    readonly apiToken: string;
+    readonly clientId: string;
+    readonly userId: string;
+}
+declare const HabiticaConfig_base: Context.ServiceClass<HabiticaConfig, "habitica-mcp/HabiticaConfig", HabiticaConfigShape>;
+export declare class HabiticaConfig extends HabiticaConfig_base {
+    static readonly layer: Layer.Layer<HabiticaConfig, Config.ConfigError, never>;
+    static readonly from: (config: HabiticaConfigShape) => Layer.Layer<HabiticaConfig, never, never>;
+}
+export {};

package/dist/config/HabiticaConfig.js

@@ -0,0 +1,16 @@
+import { Config, Context, Effect, Layer, Redacted } from "effect";
+export class HabiticaConfig extends Context.Service()("habitica-mcp/HabiticaConfig") {
+    static layer = Layer.effect(HabiticaConfig, Effect.gen(function* () {
+        const userId = yield* Config.string("HABITICA_USER_ID");
+        const apiToken = yield* Config.redacted("HABITICA_API_TOKEN");
+        const clientId = yield* Config.string("HABITICA_CLIENT_ID");
+        const apiBaseUrl = yield* Config.string("HABITICA_API_BASE_URL").pipe(Config.withDefault("https://habitica.com/api/v3"));
+        return HabiticaConfig.of({
+            apiBaseUrl,
+            apiToken: Redacted.value(apiToken),
+            clientId,
+            userId,
+        });
+    }));
+    static from = (config) => Layer.succeed(HabiticaConfig)(HabiticaConfig.of(config));
+}

package/dist/habitica/HabiticaErrors.d.ts

@@ -0,0 +1,35 @@
+import { Schema } from "effect";
+declare const HabiticaConfigError_base: Schema.Class<HabiticaConfigError, Schema.TaggedStruct<"HabiticaConfigError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class HabiticaConfigError extends HabiticaConfigError_base {
+}
+declare const HabiticaAuthError_base: Schema.Class<HabiticaAuthError, Schema.TaggedStruct<"HabiticaAuthError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class HabiticaAuthError extends HabiticaAuthError_base {
+}
+declare const HabiticaRateLimitError_base: Schema.Class<HabiticaRateLimitError, Schema.TaggedStruct<"HabiticaRateLimitError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class HabiticaRateLimitError extends HabiticaRateLimitError_base {
+}
+declare const HabiticaNotFoundError_base: Schema.Class<HabiticaNotFoundError, Schema.TaggedStruct<"HabiticaNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class HabiticaNotFoundError extends HabiticaNotFoundError_base {
+}
+declare const HabiticaApiError_base: Schema.Class<HabiticaApiError, Schema.TaggedStruct<"HabiticaApiError", {
+    readonly message: Schema.String;
+    readonly status: Schema.optional<Schema.Number>;
+}>, import("effect/Cause").YieldableError>;
+export declare class HabiticaApiError extends HabiticaApiError_base {
+}
+declare const HabiticaDecodeError_base: Schema.Class<HabiticaDecodeError, Schema.TaggedStruct<"HabiticaDecodeError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class HabiticaDecodeError extends HabiticaDecodeError_base {
+}
+export type HabiticaError = HabiticaApiError | HabiticaAuthError | HabiticaConfigError | HabiticaDecodeError | HabiticaNotFoundError | HabiticaRateLimitError;
+export declare const HabiticaErrorSchema: Schema.Union<readonly [typeof HabiticaApiError, typeof HabiticaAuthError, typeof HabiticaConfigError, typeof HabiticaDecodeError, typeof HabiticaNotFoundError, typeof HabiticaRateLimitError]>;
+export {};

package/dist/habitica/HabiticaErrors.js

@@ -0,0 +1,34 @@
+import { Schema } from "effect";
+class HabiticaConfigError extends Schema.TaggedErrorClass()("HabiticaConfigError", {
+    message: Schema.String,
+}) {
+}
+export class HabiticaAuthError extends Schema.TaggedErrorClass()("HabiticaAuthError", {
+    message: Schema.String,
+}) {
+}
+export class HabiticaRateLimitError extends Schema.TaggedErrorClass()("HabiticaRateLimitError", {
+    message: Schema.String,
+}) {
+}
+export class HabiticaNotFoundError extends Schema.TaggedErrorClass()("HabiticaNotFoundError", {
+    message: Schema.String,
+}) {
+}
+export class HabiticaApiError extends Schema.TaggedErrorClass()("HabiticaApiError", {
+    message: Schema.String,
+    status: Schema.optional(Schema.Number),
+}) {
+}
+export class HabiticaDecodeError extends Schema.TaggedErrorClass()("HabiticaDecodeError", {
+    message: Schema.String,
+}) {
+}
+export const HabiticaErrorSchema = Schema.Union([
+    HabiticaApiError,
+    HabiticaAuthError,
+    HabiticaConfigError,
+    HabiticaDecodeError,
+    HabiticaNotFoundError,
+    HabiticaRateLimitError,
+]);

package/dist/habitica/HabiticaGateway.d.ts

@@ -0,0 +1,77 @@
+import { Context, type Effect } from "effect";
+import type { HabiticaError } from "./HabiticaErrors.js";
+import type { CreateTagInput, CreateTaskInput, Direction, HabiticaInventory, HabiticaMutationResult, HabiticaNotification, HabiticaProfile, HabiticaShopItem, HabiticaSkill, HabiticaTag, HabiticaTask, TaskType, UpdateChecklistItemInput, UpdateTaskInput } from "./HabiticaSchemas.js";
+export interface HabiticaGatewayShape {
+    readonly addChecklistItem: (input: {
+        readonly taskId: string;
+        readonly text: string;
+    }) => Effect.Effect<HabiticaTask, HabiticaError>;
+    readonly buyReward: (input: {
+        readonly rewardId: string;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly buyShopItem: (input: {
+        readonly key: string;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly castSkill: (input: {
+        readonly skillKey: string;
+        readonly targetId?: string | undefined;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly createReward: (input: CreateTaskInput) => Effect.Effect<HabiticaTask, HabiticaError>;
+    readonly createTag: (input: CreateTagInput) => Effect.Effect<HabiticaTag, HabiticaError>;
+    readonly createTask: (input: CreateTaskInput) => Effect.Effect<HabiticaTask, HabiticaError>;
+    readonly deleteChecklistItem: (input: {
+        readonly itemId: string;
+        readonly taskId: string;
+    }) => Effect.Effect<HabiticaTask, HabiticaError>;
+    readonly deleteReward: (input: {
+        readonly rewardId: string;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly deleteTask: (input: {
+        readonly taskId: string;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly equipMount: (input: {
+        readonly mountKey: string;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly equipPet: (input: {
+        readonly petKey: string;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly feedPet: (input: {
+        readonly foodKey: string;
+        readonly petKey: string;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly getInventory: Effect.Effect<HabiticaInventory, HabiticaError>;
+    readonly getStats: Effect.Effect<HabiticaProfile["stats"], HabiticaError>;
+    readonly getTask: (input: {
+        readonly taskId: string;
+    }) => Effect.Effect<HabiticaTask, HabiticaError>;
+    readonly getUserProfile: Effect.Effect<HabiticaProfile, HabiticaError>;
+    readonly hatchPet: (input: {
+        readonly eggKey: string;
+        readonly hatchingPotionKey: string;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly listNotifications: Effect.Effect<ReadonlyArray<HabiticaNotification>, HabiticaError>;
+    readonly listShopItems: Effect.Effect<ReadonlyArray<HabiticaShopItem>, HabiticaError>;
+    readonly listSkills: Effect.Effect<ReadonlyArray<HabiticaSkill>, HabiticaError>;
+    readonly listTags: Effect.Effect<ReadonlyArray<HabiticaTag>, HabiticaError>;
+    readonly listTasks: (input: {
+        readonly type?: TaskType | undefined;
+    }) => Effect.Effect<ReadonlyArray<HabiticaTask>, HabiticaError>;
+    readonly readNotification: (input: {
+        readonly notificationId: string;
+    }) => Effect.Effect<HabiticaMutationResult, HabiticaError>;
+    readonly scoreChecklistItem: (input: {
+        readonly itemId: string;
+        readonly taskId: string;
+    }) => Effect.Effect<HabiticaTask, HabiticaError>;
+    readonly scoreTask: (input: {
+        readonly direction: Direction;
+        readonly taskId: string;
+    }) => Effect.Effect<HabiticaTask, HabiticaError>;
+    readonly updateChecklistItem: (input: UpdateChecklistItemInput) => Effect.Effect<HabiticaTask, HabiticaError>;
+    readonly updateReward: (input: UpdateTaskInput) => Effect.Effect<HabiticaTask, HabiticaError>;
+    readonly updateTask: (input: UpdateTaskInput) => Effect.Effect<HabiticaTask, HabiticaError>;
+}
+declare const HabiticaGateway_base: Context.ServiceClass<HabiticaGateway, "habitica-mcp/HabiticaGateway", HabiticaGatewayShape>;
+export declare class HabiticaGateway extends HabiticaGateway_base {
+}
+export {};

package/dist/habitica/HabiticaGateway.js

@@ -0,0 +1,3 @@
+import { Context } from "effect";
+export class HabiticaGateway extends Context.Service()("habitica-mcp/HabiticaGateway") {
+}

package/dist/habitica/HabiticaHttpAdapter.d.ts

@@ -0,0 +1,8 @@
+import { Layer } from "effect";
+import { HabiticaConfig } from "../config/HabiticaConfig.js";
+import { HabiticaGateway } from "./HabiticaGateway.js";
+import { HabiticaTransport } from "./HabiticaTransport.js";
+export declare const HabiticaHttpAdapter: {
+    readonly gatewayLayer: Layer.Layer<HabiticaGateway, never, HabiticaConfig>;
+    readonly transportLayer: Layer.Layer<HabiticaTransport, never, HabiticaConfig>;
+};

package/dist/habitica/HabiticaHttpAdapter.js

@@ -0,0 +1,106 @@
+import { Effect, flow, Layer, Schema } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http";
+import { HabiticaConfig } from "../config/HabiticaConfig.js";
+import { HabiticaApiError, HabiticaAuthError, HabiticaDecodeError, HabiticaNotFoundError, HabiticaRateLimitError, } from "./HabiticaErrors.js";
+import { HabiticaGateway } from "./HabiticaGateway.js";
+import { HabiticaRoutes, taskListUrlParams } from "./HabiticaRoutes.js";
+import { CreateTaskInput, HabiticaInventory, HabiticaMutationResult, HabiticaNotification, HabiticaProfile, HabiticaShopItem, HabiticaSkill, HabiticaTag, HabiticaTask, } from "./HabiticaSchemas.js";
+import { HabiticaTransport } from "./HabiticaTransport.js";
+const responseData = (schema) => Schema.Struct({
+    data: schema,
+    success: Schema.Boolean,
+});
+const decodeUnknown = (schema, value) => Effect.try({
+    try: () => Schema.decodeUnknownSync(schema)(value),
+    catch: () => new HabiticaDecodeError({
+        message: "Habitica response did not match the expected schema.",
+    }),
+});
+const decodeData = (schema) => (value) => decodeUnknown(responseData(schema), value).pipe(Effect.map((body) => body.data));
+const methodRequest = (request) => {
+    const requestForMethod = request.method === "GET"
+        ? HttpClientRequest.get(request.path)
+        : request.method === "POST"
+            ? HttpClientRequest.post(request.path)
+            : request.method === "PUT"
+                ? HttpClientRequest.put(request.path)
+                : HttpClientRequest.delete(request.path);
+    const withParams = request.urlParams === undefined
+        ? requestForMethod
+        : requestForMethod.pipe(HttpClientRequest.setUrlParams(request.urlParams));
+    return request.body === undefined
+        ? withParams
+        : withParams.pipe(HttpClientRequest.bodyJsonUnsafe(request.body));
+};
+const errorForStatus = (status) => status === 401 || status === 403
+    ? new HabiticaAuthError({ message: "Habitica rejected the configured credentials." })
+    : status === 404
+        ? new HabiticaNotFoundError({ message: "Habitica resource was not found." })
+        : status === 429
+            ? new HabiticaRateLimitError({ message: "Habitica rate limit exceeded." })
+            : new HabiticaApiError({ message: "Habitica API request failed.", status });
+const ensureOk = (response) => response.status >= 200 && response.status < 300
+    ? Effect.succeed(response)
+    : Effect.fail(errorForStatus(response.status));
+const rewardInput = (input) => input.notes === undefined
+    ? new CreateTaskInput({ text: input.text, type: "reward" })
+    : new CreateTaskInput({ notes: input.notes, text: input.text, type: "reward" });
+const transportLayer = Layer.effect(HabiticaTransport, Effect.gen(function* () {
+    const config = yield* HabiticaConfig;
+    const client = (yield* HttpClient.HttpClient).pipe(HttpClient.mapRequest(flow(HttpClientRequest.prependUrl(config.apiBaseUrl), HttpClientRequest.acceptJson, HttpClientRequest.setHeaders({
+        "x-api-key": config.apiToken,
+        "x-api-user": config.userId,
+        "x-client": config.clientId,
+    }))));
+    return HabiticaTransport.of({
+        request: (request, decode) => client.execute(methodRequest(request)).pipe(Effect.flatMap(ensureOk), Effect.flatMap(HttpClientResponse.schemaBodyJson(Schema.Unknown)), Effect.flatMap(decode), Effect.mapError((error) => error instanceof HabiticaAuthError ||
+            error instanceof HabiticaApiError ||
+            error instanceof HabiticaDecodeError ||
+            error instanceof HabiticaNotFoundError ||
+            error instanceof HabiticaRateLimitError
+            ? error
+            : new HabiticaApiError({ message: "Habitica HTTP transport failed." }))),
+    });
+})).pipe(Layer.provide(FetchHttpClient.layer));
+const gatewayLayer = Layer.effect(HabiticaGateway, Effect.gen(function* () {
+    const transport = yield* HabiticaTransport;
+    const get = (path, schema, urlParams) => transport.request(urlParams === undefined ? { method: "GET", path } : { method: "GET", path, urlParams }, decodeData(schema));
+    const post = (path, body, schema) => transport.request({ body, method: "POST", path }, decodeData(schema));
+    const put = (path, body, schema) => transport.request({ body, method: "PUT", path }, decodeData(schema));
+    const del = (path, schema) => transport.request({ method: "DELETE", path }, decodeData(schema));
+    return HabiticaGateway.of({
+        addChecklistItem: ({ taskId, text }) => post(HabiticaRoutes.checklist(taskId), { text }, HabiticaTask),
+        buyReward: ({ rewardId }) => post(HabiticaRoutes.taskScore(rewardId, "down"), {}, HabiticaMutationResult),
+        buyShopItem: ({ key }) => post(HabiticaRoutes.buySpecialSpell(key), {}, HabiticaMutationResult),
+        castSkill: ({ skillKey, targetId }) => post(HabiticaRoutes.castSkill(skillKey), { targetId }, HabiticaMutationResult),
+        createReward: (input) => post(HabiticaRoutes.tasksUser(), rewardInput(input), HabiticaTask),
+        createTag: (input) => post(HabiticaRoutes.tags(), input, HabiticaTag),
+        createTask: (input) => post(HabiticaRoutes.tasksUser(), input, HabiticaTask),
+        deleteChecklistItem: ({ itemId, taskId }) => del(HabiticaRoutes.checklistItem(taskId, itemId), HabiticaTask),
+        deleteReward: ({ rewardId }) => del(HabiticaRoutes.task(rewardId), HabiticaMutationResult),
+        deleteTask: ({ taskId }) => del(HabiticaRoutes.task(taskId), HabiticaMutationResult),
+        equipMount: ({ mountKey }) => post(HabiticaRoutes.equipMount(mountKey), {}, HabiticaMutationResult),
+        equipPet: ({ petKey }) => post(HabiticaRoutes.equipPet(petKey), {}, HabiticaMutationResult),
+        feedPet: ({ foodKey, petKey }) => post(HabiticaRoutes.feedPet(petKey, foodKey), {}, HabiticaMutationResult),
+        getInventory: get(HabiticaRoutes.inventory(), HabiticaInventory),
+        getStats: get(HabiticaRoutes.user(), HabiticaProfile).pipe(Effect.map((profile) => profile.stats)),
+        getTask: ({ taskId }) => get(HabiticaRoutes.task(taskId), HabiticaTask),
+        getUserProfile: get(HabiticaRoutes.user(), HabiticaProfile),
+        hatchPet: ({ eggKey, hatchingPotionKey }) => post(HabiticaRoutes.hatchPet(eggKey, hatchingPotionKey), {}, HabiticaMutationResult),
+        listNotifications: get(HabiticaRoutes.notifications(), Schema.Array(HabiticaNotification)),
+        listShopItems: get(HabiticaRoutes.market(), Schema.Array(HabiticaShopItem)),
+        listSkills: get(HabiticaRoutes.skillList(), Schema.Array(HabiticaSkill)),
+        listTags: get(HabiticaRoutes.tags(), Schema.Array(HabiticaTag)),
+        listTasks: (input) => get(HabiticaRoutes.tasksUser(), Schema.Array(HabiticaTask), taskListUrlParams(input.type)),
+        readNotification: ({ notificationId }) => post(HabiticaRoutes.notificationRead(notificationId), {}, HabiticaMutationResult),
+        scoreChecklistItem: ({ itemId, taskId }) => post(HabiticaRoutes.checklistItemScore(taskId, itemId), {}, HabiticaTask),
+        scoreTask: ({ direction, taskId, }) => post(HabiticaRoutes.taskScore(taskId, direction), {}, HabiticaTask),
+        updateChecklistItem: (input) => put(HabiticaRoutes.checklistItem(input.taskId, input.itemId), input, HabiticaTask),
+        updateReward: (input) => put(HabiticaRoutes.task(input.id), input, HabiticaTask),
+        updateTask: (input) => put(HabiticaRoutes.task(input.id), input, HabiticaTask),
+    });
+})).pipe(Layer.provide(transportLayer));
+export const HabiticaHttpAdapter = {
+    gatewayLayer,
+    transportLayer,
+};

package/dist/habitica/HabiticaRoutes.d.ts

@@ -0,0 +1,23 @@
+import type { Direction, TaskType } from "./HabiticaSchemas.js";
+export declare const HabiticaRoutes: {
+    buySpecialSpell: (key: string) => string;
+    castSkill: (skillKey: string) => string;
+    checklist: (taskId: string) => string;
+    checklistItem: (taskId: string, itemId: string) => string;
+    checklistItemScore: (taskId: string, itemId: string) => string;
+    equipMount: (mountKey: string) => string;
+    equipPet: (petKey: string) => string;
+    feedPet: (petKey: string, foodKey: string) => string;
+    hatchPet: (eggKey: string, hatchingPotionKey: string) => string;
+    inventory: () => string;
+    market: () => string;
+    notificationRead: (notificationId: string) => string;
+    notifications: () => string;
+    skillList: () => string;
+    tags: () => string;
+    task: (taskId: string) => string;
+    taskScore: (taskId: string, direction: Direction) => string;
+    tasksUser: () => string;
+    user: () => string;
+};
+export declare const taskListUrlParams: (type: TaskType | undefined) => Readonly<Record<string, string>> | undefined;

package/dist/habitica/HabiticaRoutes.js

@@ -0,0 +1,22 @@
+export const HabiticaRoutes = {
+    buySpecialSpell: (key) => `/user/buy-special-spell/${key}`,
+    castSkill: (skillKey) => `/user/class/cast/${skillKey}`,
+    checklist: (taskId) => `/tasks/${taskId}/checklist`,
+    checklistItem: (taskId, itemId) => `/tasks/${taskId}/checklist/${itemId}`,
+    checklistItemScore: (taskId, itemId) => `/tasks/${taskId}/checklist/${itemId}/score`,
+    equipMount: (mountKey) => `/user/equip/mount/${mountKey}`,
+    equipPet: (petKey) => `/user/equip/pet/${petKey}`,
+    feedPet: (petKey, foodKey) => `/user/feed/${petKey}/${foodKey}`,
+    hatchPet: (eggKey, hatchingPotionKey) => `/user/hatch/${eggKey}/${hatchingPotionKey}`,
+    inventory: () => "/user/inventory",
+    market: () => "/shops/market",
+    notificationRead: (notificationId) => `/notifications/${notificationId}/read`,
+    notifications: () => "/notifications",
+    skillList: () => "/user/class/cast",
+    tags: () => "/tags",
+    task: (taskId) => `/tasks/${taskId}`,
+    taskScore: (taskId, direction) => `/tasks/${taskId}/score/${direction}`,
+    tasksUser: () => "/tasks/user",
+    user: () => "/user",
+};
+export const taskListUrlParams = (type) => (type === undefined ? undefined : { type });

package/dist/habitica/HabiticaSchemas.d.ts

@@ -0,0 +1,111 @@
+import { Schema } from "effect";
+export declare const TaskType: Schema.Literals<readonly ["habit", "daily", "todo", "reward"]>;
+export type TaskType = typeof TaskType.Type;
+export declare const Direction: Schema.Literals<readonly ["up", "down"]>;
+export type Direction = typeof Direction.Type;
+declare const HabiticaStats_base: Schema.Class<HabiticaStats, Schema.Struct<{
+    readonly class: Schema.optional<Schema.String>;
+    readonly gp: Schema.Number;
+    readonly hp: Schema.Number;
+    readonly lvl: Schema.Number;
+    readonly mp: Schema.Number;
+    readonly toNextLevel: Schema.optional<Schema.Number>;
+}>, {}>;
+declare class HabiticaStats extends HabiticaStats_base {
+}
+declare const HabiticaProfile_base: Schema.Class<HabiticaProfile, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly displayName: Schema.String;
+    readonly stats: typeof HabiticaStats;
+}>, {}>;
+export declare class HabiticaProfile extends HabiticaProfile_base {
+}
+declare const HabiticaChecklistItem_base: Schema.Class<HabiticaChecklistItem, Schema.Struct<{
+    readonly completed: Schema.Boolean;
+    readonly id: Schema.String;
+    readonly text: Schema.String;
+}>, {}>;
+export declare class HabiticaChecklistItem extends HabiticaChecklistItem_base {
+}
+declare const HabiticaTask_base: Schema.Class<HabiticaTask, Schema.Struct<{
+    readonly checklist: Schema.optional<Schema.$Array<typeof HabiticaChecklistItem>>;
+    readonly completed: Schema.optional<Schema.Boolean>;
+    readonly id: Schema.String;
+    readonly notes: Schema.optional<Schema.String>;
+    readonly text: Schema.String;
+    readonly type: Schema.Literals<readonly ["habit", "daily", "todo", "reward"]>;
+}>, {}>;
+export declare class HabiticaTask extends HabiticaTask_base {
+}
+declare const HabiticaTag_base: Schema.Class<HabiticaTag, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly name: Schema.String;
+}>, {}>;
+export declare class HabiticaTag extends HabiticaTag_base {
+}
+declare const HabiticaNotification_base: Schema.Class<HabiticaNotification, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly seen: Schema.Boolean;
+    readonly text: Schema.String;
+    readonly type: Schema.String;
+}>, {}>;
+export declare class HabiticaNotification extends HabiticaNotification_base {
+}
+declare const HabiticaInventory_base: Schema.Class<HabiticaInventory, Schema.Struct<{
+    readonly eggs: Schema.$Record<Schema.String, Schema.Number>;
+    readonly food: Schema.$Record<Schema.String, Schema.Number>;
+    readonly hatchingPotions: Schema.$Record<Schema.String, Schema.Number>;
+    readonly mounts: Schema.$Record<Schema.String, Schema.Boolean>;
+    readonly pets: Schema.$Record<Schema.String, Schema.Number>;
+}>, {}>;
+export declare class HabiticaInventory extends HabiticaInventory_base {
+}
+declare const HabiticaShopItem_base: Schema.Class<HabiticaShopItem, Schema.Struct<{
+    readonly key: Schema.String;
+    readonly text: Schema.String;
+    readonly value: Schema.Number;
+}>, {}>;
+export declare class HabiticaShopItem extends HabiticaShopItem_base {
+}
+declare const HabiticaSkill_base: Schema.Class<HabiticaSkill, Schema.Struct<{
+    readonly key: Schema.String;
+    readonly mana: Schema.Number;
+    readonly text: Schema.String;
+}>, {}>;
+export declare class HabiticaSkill extends HabiticaSkill_base {
+}
+declare const HabiticaMutationResult_base: Schema.Class<HabiticaMutationResult, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly message: Schema.String;
+}>, {}>;
+export declare class HabiticaMutationResult extends HabiticaMutationResult_base {
+}
+declare const CreateTaskInput_base: Schema.Class<CreateTaskInput, Schema.Struct<{
+    readonly notes: Schema.optional<Schema.String>;
+    readonly text: Schema.String;
+    readonly type: Schema.Literals<readonly ["habit", "daily", "todo", "reward"]>;
+}>, {}>;
+export declare class CreateTaskInput extends CreateTaskInput_base {
+}
+declare const UpdateTaskInput_base: Schema.Class<UpdateTaskInput, Schema.Struct<{
+    readonly completed: Schema.optional<Schema.Boolean>;
+    readonly id: Schema.String;
+    readonly notes: Schema.optional<Schema.String>;
+    readonly text: Schema.optional<Schema.String>;
+}>, {}>;
+export declare class UpdateTaskInput extends UpdateTaskInput_base {
+}
+declare const CreateTagInput_base: Schema.Class<CreateTagInput, Schema.Struct<{
+    readonly name: Schema.String;
+}>, {}>;
+export declare class CreateTagInput extends CreateTagInput_base {
+}
+declare const UpdateChecklistItemInput_base: Schema.Class<UpdateChecklistItemInput, Schema.Struct<{
+    readonly completed: Schema.optional<Schema.Boolean>;
+    readonly itemId: Schema.String;
+    readonly taskId: Schema.String;
+    readonly text: Schema.optional<Schema.String>;
+}>, {}>;
+export declare class UpdateChecklistItemInput extends UpdateChecklistItemInput_base {
+}
+export {};

package/dist/habitica/HabiticaSchemas.js

@@ -0,0 +1,94 @@
+import { Schema } from "effect";
+export const TaskType = Schema.Literals(["habit", "daily", "todo", "reward"]);
+export const Direction = Schema.Literals(["up", "down"]);
+class HabiticaStats extends Schema.Class("HabiticaStats")({
+    class: Schema.optional(Schema.String),
+    gp: Schema.Number,
+    hp: Schema.Number,
+    lvl: Schema.Number,
+    mp: Schema.Number,
+    toNextLevel: Schema.optional(Schema.Number),
+}) {
+}
+export class HabiticaProfile extends Schema.Class("HabiticaProfile")({
+    id: Schema.String,
+    displayName: Schema.String,
+    stats: HabiticaStats,
+}) {
+}
+export class HabiticaChecklistItem extends Schema.Class("HabiticaChecklistItem")({
+    completed: Schema.Boolean,
+    id: Schema.String,
+    text: Schema.String,
+}) {
+}
+export class HabiticaTask extends Schema.Class("HabiticaTask")({
+    checklist: Schema.optional(Schema.Array(HabiticaChecklistItem)),
+    completed: Schema.optional(Schema.Boolean),
+    id: Schema.String,
+    notes: Schema.optional(Schema.String),
+    text: Schema.String,
+    type: TaskType,
+}) {
+}
+export class HabiticaTag extends Schema.Class("HabiticaTag")({
+    id: Schema.String,
+    name: Schema.String,
+}) {
+}
+export class HabiticaNotification extends Schema.Class("HabiticaNotification")({
+    id: Schema.String,
+    seen: Schema.Boolean,
+    text: Schema.String,
+    type: Schema.String,
+}) {
+}
+export class HabiticaInventory extends Schema.Class("HabiticaInventory")({
+    eggs: Schema.Record(Schema.String, Schema.Number),
+    food: Schema.Record(Schema.String, Schema.Number),
+    hatchingPotions: Schema.Record(Schema.String, Schema.Number),
+    mounts: Schema.Record(Schema.String, Schema.Boolean),
+    pets: Schema.Record(Schema.String, Schema.Number),
+}) {
+}
+export class HabiticaShopItem extends Schema.Class("HabiticaShopItem")({
+    key: Schema.String,
+    text: Schema.String,
+    value: Schema.Number,
+}) {
+}
+export class HabiticaSkill extends Schema.Class("HabiticaSkill")({
+    key: Schema.String,
+    mana: Schema.Number,
+    text: Schema.String,
+}) {
+}
+export class HabiticaMutationResult extends Schema.Class("HabiticaMutationResult")({
+    id: Schema.String,
+    message: Schema.String,
+}) {
+}
+export class CreateTaskInput extends Schema.Class("CreateTaskInput")({
+    notes: Schema.optional(Schema.String),
+    text: Schema.String,
+    type: TaskType,
+}) {
+}
+export class UpdateTaskInput extends Schema.Class("UpdateTaskInput")({
+    completed: Schema.optional(Schema.Boolean),
+    id: Schema.String,
+    notes: Schema.optional(Schema.String),
+    text: Schema.optional(Schema.String),
+}) {
+}
+export class CreateTagInput extends Schema.Class("CreateTagInput")({
+    name: Schema.String,
+}) {
+}
+export class UpdateChecklistItemInput extends Schema.Class("UpdateChecklistItemInput")({
+    completed: Schema.optional(Schema.Boolean),
+    itemId: Schema.String,
+    taskId: Schema.String,
+    text: Schema.optional(Schema.String),
+}) {
+}

package/dist/habitica/HabiticaTransport.d.ts

@@ -0,0 +1,15 @@
+import { Context, type Effect } from "effect";
+import type { HabiticaError } from "./HabiticaErrors.js";
+export interface HabiticaTransportRequest {
+    readonly body?: unknown;
+    readonly method: "DELETE" | "GET" | "POST" | "PUT";
+    readonly path: string;
+    readonly urlParams?: Readonly<Record<string, string>>;
+}
+export interface HabiticaTransportShape {
+    readonly request: <A>(request: HabiticaTransportRequest, decode: (value: unknown) => Effect.Effect<A, HabiticaError>) => Effect.Effect<A, HabiticaError>;
+}
+declare const HabiticaTransport_base: Context.ServiceClass<HabiticaTransport, "habitica-mcp/HabiticaTransport", HabiticaTransportShape>;
+export declare class HabiticaTransport extends HabiticaTransport_base {
+}
+export {};

package/dist/habitica/HabiticaTransport.js

@@ -0,0 +1,3 @@
+import { Context } from "effect";
+export class HabiticaTransport extends Context.Service()("habitica-mcp/HabiticaTransport") {
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "./HabiticaMcp.js";
+run();

package/dist/prompts/HabiticaPrompts.d.ts

@@ -0,0 +1,3 @@
+export declare const DailyPlanningPrompt: import("effect/Layer").Layer<never, never, never>;
+export declare const TaskReviewPrompt: import("effect/Layer").Layer<never, never, never>;
+export declare const HabitCheckInPrompt: import("effect/Layer").Layer<never, never, never>;

package/dist/prompts/HabiticaPrompts.js

@@ -0,0 +1,35 @@
+import { Effect, Schema } from "effect";
+import { McpServer } from "effect/unstable/ai";
+export const DailyPlanningPrompt = McpServer.prompt({
+    name: "Daily Planning",
+    description: "Plan a Habitica day from current tasks and stats.",
+    parameters: {
+        focus: Schema.optional(Schema.String),
+    },
+    completion: {
+        focus: () => Effect.succeed(["dailies", "todos", "habits", "rewards"]),
+    },
+    content: ({ focus }) => Effect.succeed(`Use GetStatsTool and ListTasksTool to plan today's Habitica work${focus === undefined ? "." : ` for ${focus}.`}`),
+});
+export const TaskReviewPrompt = McpServer.prompt({
+    name: "Task Review",
+    description: "Review Habitica tasks and suggest safe updates.",
+    parameters: {
+        taskType: Schema.optional(Schema.String),
+    },
+    completion: {
+        taskType: () => Effect.succeed(["habit", "daily", "todo", "reward"]),
+    },
+    content: ({ taskType }) => Effect.succeed(`Use ListTasksTool${taskType === undefined ? "" : ` filtered to ${taskType}`} and propose explicit changes before using mutating tools.`),
+});
+export const HabitCheckInPrompt = McpServer.prompt({
+    name: "Habit Check-In",
+    description: "Check in on Habitica habits without scoring them automatically.",
+    parameters: {
+        mood: Schema.optional(Schema.String),
+    },
+    completion: {
+        mood: () => Effect.succeed(["steady", "blocked", "low-energy", "high-energy"]),
+    },
+    content: ({ mood }) => Effect.succeed(`Use ListTasksTool for habits and ask before ScoreTaskTool${mood === undefined ? "." : `; user mood: ${mood}.`}`),
+});

package/dist/resources/HabiticaResources.d.ts

@@ -0,0 +1,2 @@
+export declare const CapabilitiesResource: import("effect/Layer").Layer<never, never, never>;
+export declare const TaskTemplateResource: import("effect/Layer").Layer<never, never, never>;

package/dist/resources/HabiticaResources.js

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+import { McpServer } from "effect/unstable/ai";
+export const CapabilitiesResource = McpServer.resource({
+    uri: "habitica-mcp://capabilities",
+    name: "Habitica MCP Capabilities",
+    description: "Describes the supported Habitica read and write tool domains.",
+    mimeType: "text/markdown",
+    content: Effect.succeed(`# Habitica MCP Capabilities
+
+This server exposes typed Habitica tools for profile, stats, tasks, tags, checklists, notifications,
+inventory, rewards, shop items, pets, mounts, and skills.
+
+Mutating tools use explicit verb names and request approval. Stdio stdout is reserved for MCP JSON-RPC.`),
+});
+export const TaskTemplateResource = McpServer.resource({
+    uri: "habitica-mcp://task-template",
+    name: "Habitica Task Template",
+    description: "Suggested fields for creating or updating Habitica tasks.",
+    mimeType: "application/json",
+    content: Effect.succeed(JSON.stringify({
+        notes: "Optional notes visible on the task.",
+        text: "Clear task text.",
+        type: "habit | daily | todo | reward",
+    }, null, 2)),
+});

package/dist/tools/HabiticaTools.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/HabiticaTools.js

@@ -0,0 +1,354 @@
+import { Effect, Schema } from "effect";
+import { Tool, Toolkit } from "effect/unstable/ai";
+import { HabiticaErrorSchema } from "../habitica/HabiticaErrors.js";
+import { HabiticaGateway } from "../habitica/HabiticaGateway.js";
+import { CreateTagInput, CreateTaskInput, Direction, HabiticaInventory, HabiticaMutationResult, HabiticaNotification, HabiticaProfile, HabiticaShopItem, HabiticaSkill, HabiticaTag, HabiticaTask, TaskType, UpdateChecklistItemInput, UpdateTaskInput, } from "../habitica/HabiticaSchemas.js";
+const TaskIdInput = Schema.Struct({ taskId: Schema.String });
+const RewardIdInput = Schema.Struct({ rewardId: Schema.String });
+const NotificationIdInput = Schema.Struct({ notificationId: Schema.String });
+const ListTasksInput = Schema.Struct({ type: Schema.optional(TaskType) });
+const ScoreTaskInput = Schema.Struct({ direction: Direction, taskId: Schema.String });
+const AddChecklistItemInput = Schema.Struct({ taskId: Schema.String, text: Schema.String });
+const DeleteChecklistItemInput = Schema.Struct({ itemId: Schema.String, taskId: Schema.String });
+const PetFoodInput = Schema.Struct({ foodKey: Schema.String, petKey: Schema.String });
+const HatchPetInput = Schema.Struct({ eggKey: Schema.String, hatchingPotionKey: Schema.String });
+const PetInput = Schema.Struct({ petKey: Schema.String });
+const MountInput = Schema.Struct({ mountKey: Schema.String });
+const SkillInput = Schema.Struct({
+    skillKey: Schema.String,
+    targetId: Schema.optional(Schema.String),
+});
+const ShopItemInput = Schema.Struct({ key: Schema.String });
+const HelloWorldInput = Schema.Struct({ name: Schema.optional(Schema.String) });
+const HabiticaFailure = { failure: HabiticaErrorSchema };
+const HelloWorldTool = Tool.make("HelloWorldTool", {
+    description: "Return a deterministic greeting for MCP smoke tests.",
+    parameters: HelloWorldInput,
+    success: Schema.String,
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, false);
+const GetUserProfileTool = Tool.make("GetUserProfileTool", {
+    ...HabiticaFailure,
+    description: "Read the current Habitica user profile.",
+    success: HabiticaProfile,
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const GetStatsTool = Tool.make("GetStatsTool", {
+    ...HabiticaFailure,
+    description: "Read the current Habitica stat block.",
+    success: HabiticaProfile.fields.stats,
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const ListTasksTool = Tool.make("ListTasksTool", {
+    ...HabiticaFailure,
+    description: "Read Habitica tasks, optionally filtered by task type.",
+    parameters: ListTasksInput,
+    success: Schema.Array(HabiticaTask),
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const GetTaskTool = Tool.make("GetTaskTool", {
+    ...HabiticaFailure,
+    description: "Read a single Habitica task by id.",
+    parameters: TaskIdInput,
+    success: HabiticaTask,
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const ListTagsTool = Tool.make("ListTagsTool", {
+    ...HabiticaFailure,
+    description: "Read Habitica tags.",
+    success: Schema.Array(HabiticaTag),
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const GetInventoryTool = Tool.make("GetInventoryTool", {
+    ...HabiticaFailure,
+    description: "Read Habitica inventory state.",
+    success: HabiticaInventory,
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const ListNotificationsTool = Tool.make("ListNotificationsTool", {
+    ...HabiticaFailure,
+    description: "Read Habitica notifications.",
+    success: Schema.Array(HabiticaNotification),
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const CreateTaskTool = Tool.make("CreateTaskTool", {
+    ...HabiticaFailure,
+    description: "Create a Habitica task.",
+    parameters: CreateTaskInput,
+    success: HabiticaTask,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const UpdateTaskTool = Tool.make("UpdateTaskTool", {
+    ...HabiticaFailure,
+    description: "Update a Habitica task.",
+    parameters: UpdateTaskInput,
+    success: HabiticaTask,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const DeleteTaskTool = Tool.make("DeleteTaskTool", {
+    ...HabiticaFailure,
+    description: "Delete a Habitica task.",
+    parameters: TaskIdInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, true)
+    .annotate(Tool.OpenWorld, true);
+const ScoreTaskTool = Tool.make("ScoreTaskTool", {
+    ...HabiticaFailure,
+    description: "Score a Habitica task up or down.",
+    parameters: ScoreTaskInput,
+    success: HabiticaTask,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const CreateTagTool = Tool.make("CreateTagTool", {
+    ...HabiticaFailure,
+    description: "Create a Habitica tag.",
+    parameters: CreateTagInput,
+    success: HabiticaTag,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const AddChecklistItemTool = Tool.make("AddChecklistItemTool", {
+    ...HabiticaFailure,
+    description: "Create a checklist item on a Habitica task.",
+    parameters: AddChecklistItemInput,
+    success: HabiticaTask,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const UpdateChecklistItemTool = Tool.make("UpdateChecklistItemTool", {
+    ...HabiticaFailure,
+    description: "Update a Habitica task checklist item.",
+    parameters: UpdateChecklistItemInput,
+    success: HabiticaTask,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const DeleteChecklistItemTool = Tool.make("DeleteChecklistItemTool", {
+    ...HabiticaFailure,
+    description: "Delete a Habitica task checklist item.",
+    parameters: DeleteChecklistItemInput,
+    success: HabiticaTask,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, true)
+    .annotate(Tool.OpenWorld, true);
+const ScoreChecklistItemTool = Tool.make("ScoreChecklistItemTool", {
+    ...HabiticaFailure,
+    description: "Score a Habitica task checklist item.",
+    parameters: DeleteChecklistItemInput,
+    success: HabiticaTask,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const ReadNotificationTool = Tool.make("ReadNotificationTool", {
+    ...HabiticaFailure,
+    description: "Mark a Habitica notification as read.",
+    parameters: NotificationIdInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const ListRewardsTool = Tool.make("ListRewardsTool", {
+    ...HabiticaFailure,
+    description: "Read Habitica reward tasks.",
+    success: Schema.Array(HabiticaTask),
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const CreateRewardTool = Tool.make("CreateRewardTool", {
+    ...HabiticaFailure,
+    description: "Create a Habitica reward.",
+    parameters: CreateTaskInput,
+    success: HabiticaTask,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const UpdateRewardTool = Tool.make("UpdateRewardTool", {
+    ...HabiticaFailure,
+    description: "Update a Habitica reward.",
+    parameters: UpdateTaskInput,
+    success: HabiticaTask,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const DeleteRewardTool = Tool.make("DeleteRewardTool", {
+    ...HabiticaFailure,
+    description: "Delete a Habitica reward.",
+    parameters: RewardIdInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, true)
+    .annotate(Tool.OpenWorld, true);
+const BuyRewardTool = Tool.make("BuyRewardTool", {
+    ...HabiticaFailure,
+    description: "Buy a Habitica reward.",
+    parameters: RewardIdInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const ListShopItemsTool = Tool.make("ListShopItemsTool", {
+    ...HabiticaFailure,
+    description: "Read Habitica shop items.",
+    success: Schema.Array(HabiticaShopItem),
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const BuyShopItemTool = Tool.make("BuyShopItemTool", {
+    ...HabiticaFailure,
+    description: "Buy a Habitica shop item.",
+    parameters: ShopItemInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const HatchPetTool = Tool.make("HatchPetTool", {
+    ...HabiticaFailure,
+    description: "Hatch a Habitica pet.",
+    parameters: HatchPetInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const FeedPetTool = Tool.make("FeedPetTool", {
+    ...HabiticaFailure,
+    description: "Feed a Habitica pet.",
+    parameters: PetFoodInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const EquipPetTool = Tool.make("EquipPetTool", {
+    ...HabiticaFailure,
+    description: "Equip a Habitica pet.",
+    parameters: PetInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const EquipMountTool = Tool.make("EquipMountTool", {
+    ...HabiticaFailure,
+    description: "Equip a Habitica mount.",
+    parameters: MountInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const ListSkillsTool = Tool.make("ListSkillsTool", {
+    ...HabiticaFailure,
+    description: "Read usable Habitica skills.",
+    success: Schema.Array(HabiticaSkill),
+})
+    .annotate(Tool.Readonly, true)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+const CastSkillTool = Tool.make("CastSkillTool", {
+    ...HabiticaFailure,
+    description: "Cast a Habitica skill.",
+    parameters: SkillInput,
+    success: HabiticaMutationResult,
+    needsApproval: true,
+})
+    .annotate(Tool.Readonly, false)
+    .annotate(Tool.Destructive, false)
+    .annotate(Tool.OpenWorld, true);
+/** @internal */
+export const HabiticaToolkit = Toolkit.make(HelloWorldTool, GetUserProfileTool, GetStatsTool, ListTasksTool, GetTaskTool, ListTagsTool, GetInventoryTool, ListNotificationsTool, CreateTaskTool, UpdateTaskTool, DeleteTaskTool, ScoreTaskTool, CreateTagTool, AddChecklistItemTool, UpdateChecklistItemTool, DeleteChecklistItemTool, ScoreChecklistItemTool, ReadNotificationTool, ListRewardsTool, CreateRewardTool, UpdateRewardTool, DeleteRewardTool, BuyRewardTool, ListShopItemsTool, BuyShopItemTool, HatchPetTool, FeedPetTool, EquipPetTool, EquipMountTool, ListSkillsTool, CastSkillTool);
+/** @internal */
+export const HabiticaToolHandlers = Effect.gen(function* () {
+    const gateway = yield* HabiticaGateway;
+    return HabiticaToolkit.of({
+        AddChecklistItemTool: gateway.addChecklistItem,
+        BuyRewardTool: gateway.buyReward,
+        BuyShopItemTool: gateway.buyShopItem,
+        CastSkillTool: gateway.castSkill,
+        CreateRewardTool: gateway.createReward,
+        CreateTagTool: gateway.createTag,
+        CreateTaskTool: gateway.createTask,
+        DeleteChecklistItemTool: gateway.deleteChecklistItem,
+        DeleteRewardTool: gateway.deleteReward,
+        DeleteTaskTool: gateway.deleteTask,
+        EquipMountTool: gateway.equipMount,
+        EquipPetTool: gateway.equipPet,
+        FeedPetTool: gateway.feedPet,
+        GetInventoryTool: () => gateway.getInventory,
+        GetStatsTool: () => gateway.getStats,
+        GetTaskTool: gateway.getTask,
+        GetUserProfileTool: () => gateway.getUserProfile,
+        HelloWorldTool: ({ name }) => Effect.succeed(`Hello, ${name ?? "world"}!`),
+        HatchPetTool: gateway.hatchPet,
+        ListNotificationsTool: () => gateway.listNotifications,
+        ListRewardsTool: () => gateway.listTasks({ type: "reward" }),
+        ListShopItemsTool: () => gateway.listShopItems,
+        ListSkillsTool: () => gateway.listSkills,
+        ListTagsTool: () => gateway.listTags,
+        ListTasksTool: gateway.listTasks,
+        ReadNotificationTool: gateway.readNotification,
+        ScoreChecklistItemTool: gateway.scoreChecklistItem,
+        ScoreTaskTool: gateway.scoreTask,
+        UpdateChecklistItemTool: gateway.updateChecklistItem,
+        UpdateRewardTool: gateway.updateReward,
+        UpdateTaskTool: gateway.updateTask,
+    });
+});
+/** @internal */
+export const HabiticaToolLayer = HabiticaToolkit.toLayer(HabiticaToolHandlers);

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "habitica-mcp",
+  "version": "0.0.1-alpha.0",
+  "description": "Habitica Model Context Protocol server built with Effect v4 beta",
+  "keywords": [
+    "effect",
+    "habitica",
+    "mcp",
+    "model-context-protocol",
+    "typescript"
+  ],
+  "homepage": "https://github.com/tatemz/habitica-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/tatemz/habitica-mcp/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tatemz/habitica-mcp.git"
+  },
+  "bin": {
+    "habitica-mcp": "dist/main.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": [],
+  "main": "./dist/HabiticaMcp.js",
+  "types": "./dist/HabiticaMcp.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/HabiticaMcp.d.ts",
+      "default": "./dist/HabiticaMcp.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
+    "check": "pnpm build && pnpm typecheck && pnpm lint && pnpm format:check && pnpm test:coverage && pnpm e2e && pnpm mutation && pnpm lint:knip",
+    "dev": "tsx src/main.ts",
+    "e2e": "NODE_OPTIONS=\"--import tsx\" effect-bdd --features \"e2e/**/*.feature\" --steps \"e2e/**/*.step.ts\" --reporter text --strict",
+    "format": "oxfmt .",
+    "format:check": "oxfmt . --check",
+    "lint": "pnpm lint:policy && pnpm lint:rules && pnpm lint:versions && pnpm lint:quality-scope && pnpm lint:deps && pnpm lint:custom-rule-tests && pnpm lint:oxlint",
+    "lint:custom-rule-tests": "node scripts/lint-custom-rule-tests.mjs && node --test test/unit/oxlint-rules.test.mjs",
+    "lint:deps": "depcruise --config .dependency-cruiser.cjs src test e2e scripts oxlint-plugins",
+    "lint:knip": "knip --config knip.jsonc",
+    "lint:oxlint": "oxlint . --deny-warnings",
+    "lint:policy": "node scripts/lint-suppression-policy.mjs",
+    "lint:quality-scope": "node scripts/lint-quality-scope.mjs",
+    "lint:rules": "node scripts/lint-rules-policy.mjs",
+    "lint:versions": "node scripts/lint-version-policy.mjs",
+    "mutation": "stryker run",
+    "prepack": "pnpm build",
+    "prepare": "lefthook install",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.78",
+    "effect": "4.0.0-beta.78"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
+    "@types/node": "^25.9.2",
+    "@vitest/coverage-v8": "^4.1.9",
+    "dependency-cruiser": "^17.4.3",
+    "effect-bdd": "^0.4.0",
+    "knip": "^6.16.1",
+    "lefthook": "^2.1.9",
+    "oxfmt": "^0.54.0",
+    "oxlint": "^1.69.0",
+    "oxlint-tsgolint": "^0.23.0",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "pnpm@10.16.1"
+}