habitica-mcp

一个用于自托管 Habitica 实例的 MCP 服务器，通过 Streamable HTTP 提供服务，因此它可以作为普通的网络服务运行，而不是每个客户端的 stdio 子进程。

为什么存在

现有的社区服务器（iBreaker/habitica-mcp-server）硬编码了 https://habitica.com/api/v3，仅支持 stdio，并且在创建三天后就一直未维护。对于位于 ingress 之后的自托管实例，这些都不适用。

在这里，HABITICA_BASE_URL 是必需的，没有默认值——指向错误的实例是不可能的，而不仅仅是不可取。

Related MCP server: habitca-mcp

工具

配置

端点：POST/GET/DELETE /mcp 和 GET /healthz。

设计说明

四个关键且不明显的设计决策：

响应投影，而非分页。 Habitica 的 GET /tasks/user 会在每个习惯和每日任务上返回 history: [{date, value}]——账户生命周期内每次计分事件一条记录，并且该功能默认开启。该 API 不提供 limit/offset，因此解决方案是投影：此服务器始终发送 history=false，并将每个任务投影到固定的字段集，这样上游 schema 的更改就不会悄悄地将数百 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，然后存活探针会不断杀死一个完全健康、只是没有可通信对象的进程。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 压力下被回收（1500 次顺序调用在 96 MB 堆上限下稳定在约 193 MiB），而不是泄漏，但这就是部署请求的内存比空闲占用所暗示的更多的原因。

GET /mcp 返回 405 并带有 Allow: POST。这符合规范（服务器可以拒绝独立流），也是 MCP 客户端明确期望的——它将 405 特殊处理为“这里没有服务器流”并停止。

早期版本试图通过返回一个空的 SSE 流来迎合。这导致了无限重连循环：客户端将没有携带响应的正常结束的流视为连接断开并重新调度，但其重试计数器仅在失败时递增，因此成功的空流不会重置任何内容。测量结果永远约为 1 req/s——空闲 12 秒内 GET 请求从 1 → 4 → 8 → 12，每个已连接客户端每天约 86k 次请求，且任何地方都没有错误提示。返回 405 则将其精确地保持在 1。

无状态有真正的代价，而不仅仅是好处：服务器→客户端的往返（sampling、elicitation）和主动推送的 *ListChanged 通知无法工作，因为客户端的回复会作为新的 HTTP 请求到达一个全新的服务器实例，而该实例对挂起的调用没有记忆。进度通知确实有效——它们搭载在原始请求自身的流上。对于 CRUD 工具界面来说，这些都不重要，但不要在这里依赖这些能力。

安全

/mcp 端点是未认证的。Habitica 凭据存储在服务器端，因此任何能够访问该端点的人都可以读写该账户的整个任务列表。这是有意为之的——在 MCP 端点前放置认证代理会破坏 MCP 客户端——这也是为什么部署被限制在私有网络和单个副本中。

API 令牌是用户级的 Habitica 凭据（由 Habitica 本身以明文存储），因此泄露它意味着整个账户被攻破。所有日志输出都经过脱敏记录器处理，并有一个测试断言令牌永远不会出现在任何输出的行中。

开发

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

许可证

MIT