Tyme Wear MCP Server

Model Context Protocol 서버로, Claude를 Tyme Wear 호흡 센서 플랫폼에 연결합니다. Claude를 통해 환기 데이터, 활동, 역치, 훈련 구역을 직접 분석할 수 있습니다.

traininpeaks-mcp와 동일한 아키텍처로 구축되었습니다.

Tyme Wear란?

Tyme Wear는 VitalPro 가슴 스트랩을 제조합니다. 이 웨어러블 호흡 센서는 심박수와 함께 환기 지표(호흡수, 일회 호흡량, 분당 환기량)를 측정합니다. 환기 역치(VT1, VT2)를 사용하여 개인 맞춤형 훈련 구역을 정의합니다. Team Visma | Lease a Bike에서 사용합니다.

Related MCP server: Strava MCP Server

기능

• 40개의 MCP 도구: 프로필, 활동, 호흡 데이터, VE 역치, 활동별 간결 분석, 활동 파일/감지, 훈련 계획, 운동 추천, 통합, 구독/계정, 휴식/최대 생리, 내보내기

• 시스템 키체인(macOS Keychain / Windows Credential Manager)을 통한 안전한 자격 증명 저장, 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=[...]로 옵트인)

• 공개 Streamable 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 설정 파일(~/Library/Application Support/Claude/claude_desktop_config.json, macOS 기준)에 추가하세요:

{
  "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는 호스팅된 배포를 위한 Streamable 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은 비루트 사용자로 공개 서버를 실행합니다. 런타임에 비밀을 주입하세요:

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 저장소에 연결한 다음, Production과 Preview 모두에 최소한 TYMEWEAR_PUBLIC_BEARER_TOKENS를 구성하세요. 공개 Bearer 토큰 환경 변수가 없으면 진입점이 실패 상태로 종료됩니다. Preview에는 별도의 Bearer 토큰을 사용하여 자격 증명 범위를 제한하세요. TYMEWEAR_PUBLIC_URL은 프로덕션 별칭에 권장되지만, Preview 배포는 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"을 사용하세요. Bearer 토큰을 vercel deploy --env, 셸 echo 또는 셸 기록이나 프로세스 목록에 남을 수 있는 다른 명령 인수를 통해 전달하지 마세요.

동일한 경로는 수동 복구 배포를 위해 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 통합은 기능 브랜치 및 풀 리퀘스트에 대한 Preview 배포를 생성하고, 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가 자체 등록할 수 있도록 Dynamic Client Registration을 활성화한 다음, 발급자 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, 필수 간결 분석/프로필 도구, 공개 보안/캐시 없음 헤더를 확인합니다. 또한 공개 배포가 원시 활동 읽기 또는 디스크 내보내기를 광고하지 않는지, 기본 배포가 변형 도구를 광고하지 않는지 확인합니다.

공개 클라이언트 인증

공개 모드는 단일 테넌트입니다. 업스트림 Tyme Wear에 대해 운영자 자신의 자격 증명(TYMEWEAR_EMAIL / TYMEWEAR_PASSWORD, 서버 측 환경 변수)으로 인증하므로, 모든 인증된 호출자는 운영자의 데이터를 읽습니다. 클라이언트는 연결이 허용되었음을 증명하기만 하면 됩니다 — 요청별 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 이메일 허용 목록에 의해 제어됩니다. 허용 목록에 있는 ID만 연결됩니다.

• 운영자의 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를 셸 기록이나 소스 제어가 아닌 비밀 관리자에서 주입합니다. 32자 미만의 토큰은 시작 시 거부됩니다.

• 프로필/활동 변형에 대한 특정 신뢰 클라이언트 요구 사항이 없는 한 공개 배포를 읽기 전용으로 유지합니다.

• 신뢰할 수 없는 클라이언트의 경우 serve-public 앞에 OAuth 또는 ID 인식 프록시를 두는 것이 좋습니다. 정적 베어러 토큰을 정기적으로 교체합니다.

• OAuth 지원 프록시 또는 권한 부여 서버를 사용하는 경우 TYMEWEAR_PUBLIC_ISSUER_URL 또는 --issuer-url을 설정하여 MCP 클라이언트가 보호된 리소스 메타데이터를 검색할 수 있도록 합니다.

• 공개 HTTP 요청 본문은 청크/스트리밍 본문을 포함하여 기본적으로 1MiB로 제한됩니다. 신뢰 배포에서 더 큰 JSON-RPC 요청이 필요한 경우에만 TYMEWEAR_PUBLIC_MAX_BODY_BYTES 또는 --max-body-bytes로 재정의합니다.

• 리버스 프록시 및 애플리케이션 플랫폼에서 권한 부여 헤더, 요청 본문 및 응답 본문 로깅을 비활성화합니다.

• 플랫폼에서 지원하는 경우 아웃바운드 네트워크 이그레스를 Tyme Wear API 호스트로 제한합니다.

• 공개 URL 호스트가 유일한 유효한 호스트/원본이 아닌 경우 명시적인 --allowed-host 및 --allowed-origin 값을 설정합니다. 공개 모드는 모든 경로에서 신뢰할 수 없는 Host 헤더를 거부하고, 와일드카드 * 호스트/원본 구성을 거부하며, 허용된 원본이 경로 없이 정확한 http(s) 원본이어야 하고, localhost가 아닌 원본은 HTTPS를 사용해야 합니다.

사용 가능한 도구

인증 및 프로필

활동

호흡 데이터

활동 파일 및 감지

훈련 계획 및 운동

통합 및 계정

임계값 및 구간

최대값

예시 프롬프트

설정이 완료되면 Claude에게 다음과 같은 질문을 할 수 있습니다:

• "최근 10개의 자전거 활동 보여줘"

• "어제 라이딩의 호흡 데이터 분석 — 평균 VE와 각 구역별 시간은?"

• "현재 사이클링 VT1 및 VT2 역치는?"

• "마지막 역치 테스트의 인사이트 가져와 — VT2에서의 파워와 VO2max 도달 여부는?"

• "마지막 활동을 FIT 파일로 내보내기"

• "달리기와 사이클링 간 VE 목표 비교"

• "현재 훈련 계획 및 운동 추천 보여줘"

• "최근 라이딩에 스트랩 파일, 로그 또는 운동 구역 감지 결과가 있는지 확인"

• "연결된 통합 및 구독 상태 나열"

보안

• 자격 증명은 시스템 키링(권장) 또는 PBKDF2 키 파생(600K 반복, 시스템별 솔트)을 사용한 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