Trainzilla Mcp

tzilla-mcp（MVP，仅限本地）

一个本地 MCP 服务，让 MCP 客户端 （Claude Desktop、Claude Code、Cursor、……）充当 Trainzilla 教练。它封装了 api.tzilla.live 上现有的 GraphQL API，不直接访问数据库，因此所有身份验证和业务规则仍由后端执行。

状态：本地 MVP — 提供读取工具、离线计算器和需确认的写入工具，以及一个资源和一个提示词。尚未部署到任何地方。完全在你的机器上运行，并使用你自己的教练账号登录。

目前可执行的操作（94 个工具、1 个资源、1 个提示词）

读取（实时数据）：

• whoami、list_clients、get_client_profile
• list_client_habits、get_habit_compliance、recent_habit_activity、master_habits
• list_workout_plans、list_diet_plans
• list_checkins、list_sessions、list_subscriptions、billing_summary

计算器（离线，无网络）：

• calc_tdee — BMR / TDEE / 推荐摄入热量
• calc_macros — 按策略计算宏量营养素配比（标准 40/30/30、专业版 g/kg、生酮）
• calc_1rm — 单次最大重量（Epley）+ %1RM 重量建议

写入（需确认）： 除非调用时设置 confirm: true，否则每个写入工具都会返回预览，避免意外更改：

• create_habit、create_master_habit、assign_master_habit
• create_checkin（含问题）、schedule_session
• create_workout_plan、create_diet_plan

出于设计考虑，目前不提供：删除、付款执行/退款、消息发送、权限更改。

资源： tzilla://client/{clientId}/profile — 以 JSON 格式提供客户资料。

提示词： weekly_client_review — 获取客户资料、习惯、完成情况和训练课程，并撰写只读的每周回顾。

设置

npm install
npm run build

创建 .env（参见 .env.example）并填入教练的令牌。最简单的获取方式是登录教练 Web 应用，然后在浏览器控制台中：

localStorage.getItem("token")        // -> TZ_ACCESS_TOKEN
localStorage.getItem("refreshToken") // -> TZ_REFRESH_TOKEN

访问令牌过期时，服务会通过 refreshAccessToken 自动刷新。

运行

本地（stdio） — 用于 Claude Desktop 等：

• 开发：npm run dev
• 构建后：npm start
• 冒烟测试：node scripts/smoke.mjs

远程（Streamable HTTP） — 仅限 localhost，支持多位教练：

• 开发：npm run http · 构建后：npm run start:http
• 监听地址：http://127.0.0.1:8787/mcp（设置 MCP_HTTP_PORT / MCP_HTTP_HOST）。
• 冒烟测试：node scripts/smoke-http.mjs

身份验证模式

• stdio： 使用环境变量中的 TZ_ACCESS_TOKEN（+ TZ_REFRESH_TOKEN）；令牌会自动刷新。
• 端点选择：
  • 设置 TZ_API_URL 时优先使用该值。
  • 否则，TZ_ENVIRONMENT=staging 时使用 https://qa-be2.tzilla.live/graphql。
  • 其他情况默认使用 https://api.tzilla.live/graphql。
• HTTP：透传 — 每个请求都必须携带教练的API 密钥 （Authorization: Bearer tz_... 或 x-api-key）。服务不会存储令牌； 而是将调用方的密钥转发给 GraphQL API，由后端强制执行权限范围 （可安全用于多位教练）。API 密钥由下方的后端功能生成。

后端：教练 API 密钥（在 tzilla-be 中构建，仅限本地 — 尚未部署）

• createApiKey(name) → 返回一次明文 tz_… 密钥及相关信息
• apiKeys（列表，不含密钥） · revokeApiKey(id)
• 身份验证中间件接受 tz_ 密钥（通过 x-api-key 标头或 Bearer），解析所属教练，并记录 lastUsedAt。仅存储 SHA-256 哈希值。

在 Claude Desktop 中使用

将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "tzilla-coach": {
      "command": "node",
      "args": ["C:/New folder/tzilla-mcp/dist/index.js"],
      "env": {
        "TZ_API_URL": "https://api.tzilla.live/graphql",
        "TZ_ACCESS_TOKEN": "<paste>",
        "TZ_REFRESH_TOKEN": "<paste>"
      }
    }
  }
}

重启 Claude Desktop，然后试试：“Use tzilla-coach：我是谁，并列出我的客户。”

路线图

• 编写工具（习惯、签到、训练课程、计划）——需确认后执行
• 资源（客户端档案）+ 提示词（每周回顾）
• 扩大读取覆盖范围（计划、签到、训练课程、账单）
• 后端训练师 API 密钥 / PAT（已在 tzilla-be 中内置，本地可用——需要 PR 并部署）
• 远程 Streamable-HTTP 传输（localhost，通过 API 密钥透传进行身份验证）
• 部署后端 API 密钥功能；托管 HTTP 服务（TLS），以支持实际远程使用
• 完整的 MCP OAuth 2.1（取代透传），用于公共连接器
• 更多资源（计划 / 签到历史）+ 提示词（例如“起草计划”）

布局

src/
  config.ts   # env + tiny .env loader
  client.ts   # GraphQL client: bearer auth + refresh-on-401 + role header
  calc.ts     # offline coach math (ported from HealthMath/WorkoutMath)
  index.ts    # MCP server + tool definitions (stdio)
scripts/
  smoke.mjs   # spawns the server and lists tools (handshake check)