habitica-mcp

セルフホストの Habitica インスタンス向けの MCP サーバーで、Streamable HTTP 上で提供されます。これにより、クライアントごとの stdio サブプロセスではなく、通常のネットワークサービスとして実行できます。

存在理由

既存のコミュニティサーバー (iBreaker/habitica-mcp-server) は https://habitica.com/api/v3 をハードコードし、stdio のみに対応し、作成から3日後以降、メンテナンスされていません。これらはすべて、イングレスの背後にあるセルフホストインスタンスでは機能しません。

ここでは、HABITICA_BASE_URL はデフォルトなしで必須です。間違ったインスタンスを指すことが、単に推奨されないのではなく、不可能になっています。

Related MCP server: habitca-mcp

ツール

設定

エンドポイント: POST/GET/DELETE /mcp、および GET /healthz。

設計メモ

重要でわかりにくい4つの決定事項:

応答のプロジェクションであり、ページネーションではない。 Habitica の GET /tasks/user は、すべての habit と daily に対して history: [{date, value}] を返します。これはアカウントの全期間にわたるスコアリングイベントごとに1エントリで、デフォルトでオンです。API には limit/offset がないため、修正はプロジェクションです。このサーバーは常に history=false を送信し、さらに各タスクを固定フィールドセットにプロジェクションするため、上流のスキーマ変更がモデルのコンテキストに数百 KB を静かに再導入することはありません。get_user_stats も同じ理由で ?userFields= を使用します。

リストフィルターは複数形で不規則です。 GET /tasks/user?type= は habits | dailys | todos | rewards | completedTodos を受け付けます（dailys に注意）。一方、作成ボディは単数形の habit | daily | todo | reward を受け取ります。ツールは単数形を公開し、内部でマッピングします。単数形をリストエンドポイントに渡すと 400 になります。

ホスト検証は /mcp に限定され、アプリ全体には適用されません。 createMcpExpressApp はこれをグローバルに適用するため、kubelet プローブ（httpGet プローブは Host: <podIP> を送信し、pod IP は許可リストに登録できない）とブラックボックス監視（Host: <svc>.<ns>.svc を送信する）の両方が壊れてしまいます。したがって /healthz はガードの外側にあります。これは何も公開せず、DNS リバインディング保護は JSON-RPC サーフェスにのみ関係します。

/healthz はプロセスの生存のみを報告し、Habitica への到達可能性は報告しません。 接続チェックを行うと、Habitica の再起動がここでは CrashLoopBackOff になり、liveness プローブが、完全に正常で単に通信相手がいないだけのプロセスを殺し続けることになります。Habitica の障害は、代わりにツールごとの明確な JSON-RPC エラーとして表面化します。

トランスポート

ステートレスな Streamable HTTP（sessionIdGenerator: undefined）で、@modelcontextprotocol/server v2 上に構築されています。これは現在の安定メジャーであり、その HTTP トランスポートは別の @modelcontextprotocol/express / @modelcontextprotocol/node アダプターにあります。ネゴシエーションされるプロトコルバージョンは 2025-11-25（SDK の LATEST_PROTOCOL_VERSION）です。v1.x は現在セキュリティとバグ修正のみです。

新しい McpServer + トランスポートはリクエストごとに作成され、レスポンスの close イベントで破棄されます。リクエストごとの構築は、見栄えのためではなく必須です。SDK v1 はステートレストランスポートの再利用で即座に例外をスローします（「Stateless transport cannot be reused across requests」）。再利用は同時クライアント間でメッセージ ID の衝突を引き起こすためです。

そのコストは現実のものであり、知っておく価値があります。各リクエストは 11 回の zod→JSON-Schema 変換を再構築し、測定では呼び出しごとに約 0.5 MB のガベージが発生します。これはリークではなく、GC プレッシャー下で回収されます（96 MB のヒープキャップで 1500 回の連続呼び出しが ~193 MiB で安定しました）。しかし、これが、デプロイがアイドル時のフットプリントが示すよりも多くのメモリを要求する理由です。

GET /mcp は Allow: POST 付きで 405 を返します。これは仕様上合法であり（サーバーはスタンドアロンストリームを拒否できます）、MCP クライアントが明示的に期待している動作です。クライアントは 405 を「ここにはサーバーストリームがない」として特別扱いし、停止します。

以前のバージョンでは、代わりに空の SSE ストリームを返すことで融通を利かせようとしていました。これにより無限再接続ループが発生しました。クライアントは、レスポンスを運ばずに正常終了したストリームを接続断とみなして再スケジュールしますが、リトライカウンタは失敗時にのみ進むため、成功した空ストリームは何もリセットしませんでした。測定では永久に ~1 req/s — 12 秒のアイドル中に 1 → 4 → 8 → 12 回の GET、接続クライアントあたり約 86k リクエスト/日で、どこにもエラーは表面化しませんでした。405 を返すことで、それを正確に 1 に保ちます。

ステートレスには利点だけでなく現実のコストがあります。サーバー→クライアントのラウンドトリップ（sampling、elicitation）と、要求されていない *ListChanged 通知は機能しません。クライアントの応答は新しい HTTP リクエストとして到着し、保留中の呼び出しの記憶を持たない新しいサーバーインスタンスに届くためです。Progress 通知は機能します — 元のリクエスト自身のストリームに乗って届きます。これらは CRUD ツールのサーフェスには関係ありませんが、ここでそれらの機能に依存して構築しないでください。

セキュリティ

/mcp エンドポイントは認証なしです。Habitica の資格情報はサーバー側にあるため、エンドポイントに到達できる人は誰でもアカウントのタスクリスト全体を読み書きできます。これは意図的です — MCP エンドポイントの前にある認証プロキシは MCP クライアントを壊すからです — また、これがデプロイがプライベートネットワークと単一レプリカに制限されている理由でもあります。

API トークンはユーザーレベルの Habitica 資格情報であり（Habitica 自身が平文で保存）、漏洩するとアカウント全体が侵害されます。すべてのログ出力は redacting ロガーを通過し、トークンが出力されるどの行にも現れないことを検証するテストがあります。

開発

npm ci
npm test
npm run lint && npm run typecheck
npm run build && node dist/index.js

ライセンス

MIT