Tyme Wear MCP 服务器

一个模型上下文协议服务器，将 Claude 连接到 Tyme Wear 呼吸传感器平台。通过 Claude 直接分析你的通气数据、活动、阈值和训练区间。

基于与 trainingpeaks-mcp 相同的架构构建。

什么是 Tyme Wear？

Tyme Wear 生产 VitalPro 胸带，这是一种可穿戴呼吸传感器，可测量通气指标（呼吸频率、潮气量、分钟通气量）以及心率。它使用通气阈值（VT1、VT2）来定义个性化的训练区间。被 Team Visma | Lease a Bike 使用。

Related MCP server: Strava MCP Server

功能

• 40 个 MCP 工具，用于个人资料、活动、呼吸数据、VE 阈值、紧凑型逐活动分析、活动文件/检测、训练计划、锻炼建议、集成、订阅/账户、静息/最大生理指标和导出

• 通过系统密钥环（macOS 钥匙串 / Windows 凭据管理器）进行安全凭据存储，并带有 AES-256-GCM 加密文件回退

• 自动认证，带有令牌缓存和过期时自动重新认证

• 智能呼吸数据，提供摘要、窗口和完整模式，避免上下文溢出

• 逐活动洞察（tw_get_activity_insights）：检测到的 VT1/VT2/VO2max，带有测量的阈值功率、置信度分数、截断测试标志以及每个区间的时间和卡路里——一次调用，无需 FIT 解析

• 紧凑型活动分析（tw_get_activity_analysis）：协调的时间戳、带标签的摘要和能力状态、每个通道的已处理/新处理/FIT 回退、确定性的已用秒数合并以及分页

• 精简的活动负载：tw_get_activity 和 tw_get_activity_workout_zone_detection 默认丢弃数 MB 的每秒数组（可通过 include=[...] 重新启用）

• 公共可流式 HTTP 模式，带有静态 Bearer 或 OAuth 认证（一键 claude.ai 连接器），单租户到操作员的 Tyme Wear 账户

快速开始

1. 安装

git clone https://github.com/tkelkermans/tymewear-mcp.git
cd tymewear-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

2. 认证

tymewear-mcp auth

输入你的 Tyme Wear 邮箱和密码。凭据将安全地存储在你的系统密钥环中，并带有加密文件回退。

3. 配置 Claude Desktop

添加到你的 Claude Desktop 配置（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "tymewear": {
      "command": "/path/to/tymewear-mcp/.venv/bin/tymewear-mcp",
      "args": ["serve"]
    }
  }
}

或者运行 tymewear-mcp config 以生成带有正确路径的代码片段。

4. 重启 Claude Desktop

Tyme Wear 工具将出现在 Claude 的工具列表中。

CLI 命令

公共互联网部署

serve-public 为托管部署暴露一个可流式 HTTP MCP 端点。它经过认证且无状态；它不是匿名公共 API。

公共服务器

通过环境变量设置公共 URL 和一个或多个 MCP Bearer 令牌。每个 Bearer 令牌必须至少 32 个字符；使用生成的随机密钥。

export TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp"
export TYMEWEAR_PUBLIC_BEARER_TOKENS="replace-with-a-long-random-secret-of-32-plus-chars"

tymewear-mcp serve-public \
  --host 0.0.0.0 \
  --port 8000 \
  --public-url "$TYMEWEAR_PUBLIC_URL"

MCP 端点默认为 /mcp。/healthz 仅返回 {"status":"ok"}，不暴露客户数据。

容器

包含的 Dockerfile 以非 root 用户身份运行公共服务器。在运行时注入密钥：

docker build -t tymewear-mcp-public .

docker run --rm -p 8000:8000 \
  -e TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp" \
  -e TYMEWEAR_PUBLIC_BEARER_TOKENS="replace-with-a-long-random-secret-of-32-plus-chars" \
  tymewear-mcp-public

Vercel

该仓库还包含一个根 Vercel Python ASGI 入口点（main.py）。Vercel 的 Python 框架直接将请求路由到 ASGI 应用，因此 vercel.json 不得将 /mcp、/healthz 或 /.well-known/* 重写为内部函数路径。将本地目录链接到目标 Vercel 项目，将该项目连接到 Git 仓库，然后为生产和预览环境至少配置 TYMEWEAR_PUBLIC_BEARER_TOKENS。如果公共 Bearer 令牌环境变量缺失，入口点将安全关闭。使用单独的预览 Bearer 令牌以限制凭据范围。建议为生产别名使用 TYMEWEAR_PUBLIC_URL，但预览部署可以从 Vercel 的部署 URL 派生。

PRODUCTION_TOKEN_FILE=/path/to/generated-production-bearer-token
PREVIEW_TOKEN_FILE=/path/to/generated-preview-bearer-token
chmod 600 "$PRODUCTION_TOKEN_FILE" "$PREVIEW_TOKEN_FILE"
vercel link
vercel git connect
vercel env add TYMEWEAR_PUBLIC_BEARER_TOKENS production --sensitive --yes < "$PRODUCTION_TOKEN_FILE"
vercel env add TYMEWEAR_PUBLIC_BEARER_TOKENS preview --sensitive --yes < "$PREVIEW_TOKEN_FILE"

保持令牌文件仅对其所有者可读；部署包装器拒绝组或其他用户可访问的令牌文件。在轮换现有令牌时，使用 vercel env update TYMEWEAR_PUBLIC_BEARER_TOKENS production --sensitive --yes < "$PRODUCTION_TOKEN_FILE"。不要通过 vercel deploy --env、shell echo 或其他可能出现在 shell 历史或进程列表中的命令参数传递 Bearer 令牌。

相同路径由 scripts/deploy_public_vercel.sh 包装，用于手动恢复部署。它需要现有的 Vercel 项目链接，从文件上传令牌，部署生产环境，并针对部署的 MCP URL 运行 scripts/verify_public_endpoint.py：

scripts/deploy_public_vercel.sh --token-file "$PRODUCTION_TOKEN_FILE"

当验证器应使用特定解释器（例如仓库虚拟环境）运行时，设置 PYTHON=/path/to/python。

自动部署（CI/CD）

.github/workflows/deploy.yml 在每次推送和拉取请求时运行锁定的测试套件（ruff + mypy + pytest）。它不持有 Vercel 凭据或部署应用程序。

链接的 Vercel Git 集成为功能分支和拉取请求创建预览部署，然后在 main 更新时创建生产部署。不需要 VERCEL_TOKEN GitHub Actions 密钥。运行时变量（如 TYMEWEAR_PUBLIC_BEARER_TOKENS）仍在 Vercel 项目中管理，并在 Git 部署之间持久化。

claude.ai 连接器（OAuth）

静态 Bearer 令牌适用于支持标头的客户端（Claude Code：claude mcp add --transport http <url> --header "Authorization: Bearer <token>"）。claude.ai 的连接器改为通过 OAuth 进行认证，因此要在此处添加 MCP，服务器作为 OAuth 受保护资源 运行：它验证来自托管提供商（例如 WorkOS AuthKit 或 Stytch）的 JWT 访问令牌，并强制执行电子邮件白名单。它保持单租户——每个授权用户通过服务器端凭据读取操作员的数据。

设置这些（敏感）Vercel 环境变量以启用它：

提供商设置（WorkOS AuthKit 示例）：创建一个应用，启用 Google/电子邮件登录，启用动态客户端注册以便 claude.ai 可以自行注册，并将颁发者 URL 复制到 TYMEWEAR_PUBLIC_ISSUER_URL。然后在 claude.ai 中添加连接器——它通过服务器的 /.well-known/oauth-protected-resource 发现提供商，注册并运行托管登录；只有白名单中的电子邮件被允许。

静态 TYMEWEAR_PUBLIC_BEARER_TOKENS 路径与 OAuth 一起保持工作（双模式）。如果没有 TYMEWEAR_PUBLIC_ISSUER_URL，OAuth 关闭，仅 Bearer 路径处于活动状态。

部署后验证

部署后，验证公共端点而不打印密钥：

TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp" \
python scripts/verify_public_endpoint.py --bearer-token-file "$TOKEN_FILE"

验证器检查 /healthz、未认证的 /mcp 拒绝、认证的 MCP initialize、认证的 tools/list、必需的紧凑分析/个人资料工具以及公共安全/无缓存标头。 它还确认公共部署不广告原始活动读取或磁盘导出，并且默认部署不广告修改工具。

公共客户端认证

公共模式是单租户：它使用操作员自己的凭据（来自 TYMEWEAR_EMAIL / TYMEWEAR_PASSWORD 的服务器端环境变量）对上游 Tyme Wear 进行认证，因此每个授权调用者读取操作员的数据。客户端只需要证明他们被允许连接——没有每个请求的 Tyme Wear 令牌。

支持标头的客户端（例如 Claude Code）发送静态网关 Bearer 令牌：

Authorization: Bearer <TYMEWEAR_PUBLIC_BEARER_TOKENS entry>

当 OAuth 启用时（设置了 TYMEWEAR_PUBLIC_ISSUER_URL），诸如 claude.ai 连接器之类的客户端改为发送通过托管登录获得的提供商颁发的 JWT；服务器验证它（通过 JWKS 签名、颁发者、可选的受众），并仅允许白名单中的电子邮件。两条路径同时工作（双模式）。

早期版本要求每个请求的 X-Tymewear-Token。单租户模式移除了它——凭据现在在服务器端。

公共数据策略

在公共模式下：

• 访问由静态 Bearer 令牌和/或 OAuth 电子邮件白名单控制；只有白名单中的身份可以连接。

• 操作员的 Tyme Wear 凭据仅存在于服务器端环境变量中（将其保存在密钥管理器中）。它们直接从环境读取——公共模式不接触本地密钥环或加密凭据文件（那些写入 $HOME，在无服务器环境中是只读的）。

• 每个工具结果和稳定的公共错误在 JSON 序列化之前通过一个非变异的递归隐私投影。它移除非 JSON 值、非有限数字、电子邮件、用户/账户/个人资料 UUID、设备标识符/序列号、令牌、签名/回调/下载 URL、S3 或临时路径、大量原始字段以及显式分析位置合同之外的坐标。

• tw_get_activity_analysis 是公共紧凑原始样本接口。它保留带标签的可用性、能力、通道、来源、摘要和分页样本数据。include_location 必须是字面布尔值 true；只有 raw_samples.data[*].position_lat/position_long 及其匹配的通道元数据可能保留。家庭、通用和不相关的坐标始终被移除。

• 公共响应包括 Cache-Control: no-store、Pragma: no-cache、X-Robots-Tag: noindex, nofollow、HTTPS 公共 URL 的 HSTS 以及基线安全标头，以减少意外中间缓存、索引和浏览器侧客户数据泄露。

• 个人资料/活动修改工具默认隐藏并返回 PUBLIC_MUTATIONS_DISABLED。仅对受信任的部署使用 --allow-mutations 或 TYMEWEAR_PUBLIC_ALLOW_MUTATIONS=true 启用它们。

• CSV、FIT 和胸带文件导出工具返回 PUBLIC_EXPORTS_DISABLED，因为本地实现将文件写入磁盘。

• tw_get_processed_data、tw_get_new_processed_data、tw_get_activity_logs 和 tw_get_activity_strap_files 默认隐藏并返回 PUBLIC_RAW_DATA_DISABLED，即使启用了修改。本地 stdio 模式保留这些工具。紧凑型锻炼区间检测保持公共。

公共工具错误稳定且不会回显上游异常文本：

生产环境加固

• 在边缘终止 TLS，并将 TYMEWEAR_PUBLIC_URL 设置为规范的 HTTPS MCP URL。

• 保持 TYMEWEAR_PUBLIC_URL 路径与挂载的 MCP 路径（默认为 /mcp）对齐。公共模式会在启动时拒绝 URL 查询参数、片段以及路由/路径不匹配。

• 从密钥管理器注入 TYMEWEAR_PUBLIC_BEARER_TOKENS，而非 shell 历史或源代码管理。短于 32 个字符的令牌会在启动时被拒绝。

• 除非有特定的受信任客户端对个人资料/活动进行变异的必需需求，否则保持公共部署为只读。

• 对于不受信任的客户端，在 serve-public 前优先使用 OAuth 或身份感知代理；定期轮换静态 Bearer 令牌。

• 使用支持 OAuth 的代理或授权服务器时，设置 TYMEWEAR_PUBLIC_ISSUER_URL 或 --issuer-url，以便 MCP 客户端能发现受保护资源的元数据。

• 默认情况下，公共 HTTP 请求体（包括分块/流式请求体）上限为 1 MiB。仅当受信任部署需要更大的 JSON-RPC 请求时，才通过 TYMEWEAR_PUBLIC_MAX_BODY_BYTES 或 --max-body-bytes 覆盖。

• 在反向代理和应用平台中保持禁用授权头、请求体和响应体的日志记录。

• 在平台支持的情况下，将出站网络出口限制为仅限 Tyme Wear API 主机。

• 当公共 URL 主机不是唯一有效的主机/来源时，设置明确的 --allowed-host 和 --allowed-origin 值。公共模式会在所有路由中拒绝不受信任的 Host 头，拒绝通配符 * 的主机/来源配置，要求允许的来源必须是精确的 http(s) 来源（不含路径），并要求非本地主机来源使用 HTTPS。

可用工具

认证与个人资料

活动

呼吸数据

活动文件与检测

训练计划与锻炼

集成与账户

阈值与心率区间

最大值

示例提示

配置完成后，您可以向 Claude 提出类似以下问题：

• "显示我最近的 10 次骑行活动"

• "分析我昨天骑行中的呼吸数据——我的平均 VE 和每个区间的时间是多少？"

• "我当前的骑行 VT1 和 VT2 阈值是多少？"

• "提取我上次阈值测试的洞察——我在 VT2 的功率是多少，是否达到了 VO2max？"

• "将我最近的活动导出为 FIT 文件"

• "比较跑步和骑行之间的 VE 目标"

• "显示我当前的训练计划和工作推荐"

• "检查我最近一次骑行是否有胸带文件、日志或训练区间检测结果"

• "列出我连接的集成和订阅状态"

安全

• 凭据存储在系统密钥环（首选）或使用 PBKDF2 密钥派生（60 万次迭代，机器特定盐值）的 AES-256-GCM 加密文件中

• 令牌和凭据绝不在 MCP 工具结果中返回（在到达 Claude 之前已清理）

• 环境变量认证适用于 CI/容器：TYMEWEAR_EMAIL + TYMEWEAR_PASSWORD

• 加密凭据文件的文件权限设置为 600（仅所有者读写）

• 公共模式需要 Bearer 或 OAuth 认证，且为单租户：上游 Tyme Wear 认证使用服务器端 TYMEWEAR_EMAIL/TYMEWEAR_PASSWORD 环境变量（绝不使用本地密钥环或加密文件，它们在无服务器环境中为只读），每个结果都经过隐私投影，且原始/文件/导出工具被禁用

架构

tymewear-mcp/
├── src/tymewear_mcp/
│   ├── cli.py              # CLI entry point
│   ├── server.py           # MCP server + 40 tool registrations
│   ├── public.py           # Public Streamable HTTP server + bearer/OAuth auth
│   ├── auth/               # Credential storage (keyring → encrypted → env) + OIDC verifier (oidc.py)
│   ├── client/             # Async HTTP client + Pydantic models
│   └── tools/              # Tool implementations (incl. threshold_analysis.py, _slimming.py)
└── tests/                  # 340 tests

技术栈： Python 3.10+, MCP SDK, httpx, Pydantic, keyring, cryptography, PyJWT

开发

pip install -e ".[dev]"
pytest tests/ -v          # Run tests
ruff check src tests      # Lint
mypy src/                 # Type check

许可证

MIT