Sport Health MCP

로컬 우선(Local-first)의 华为 운동 건강 분석 MCP Server입니다. 사용자가 한 번만 HUAWEI_HEALTH_* 개인 데이터 내보내기 패키지를 제공하면 Agent가 운동 성과, 운동 중 생리 지표, 운동 전후 건강 배경을 읽을 수 있으며, 필요에 따라 과거 날씨와 대기질 정보를 보강할 수 있습니다.

이 프로젝트는 운동 복기를 위한 것으로, 의료 진단이나 치료 조언을 제공하지 않습니다.

현재 기능

• 华为 개인 데이터 내보내기 디렉터리 및 핵심 JSON 파일을 식별합니다.

• 华为 비표준 JSON 숫자 키를 내결함성 있게 파싱합니다.

• 운동 요약, GPS 트랙, 심박수, 걸음 수, 속도, 고도, 훈련 부하를 파싱합니다.

• 운동 전날, 당일, 다음 날의 심박수, 안정 시 심박수, HRV, 스트레스, 혈중 산소, 수면 단계를 집계합니다.

• Open-Meteo의 과거 날씨 및 대기질 API를 호출하고 응답을 로컬에 캐시합니다.

• MCP를 통해 페이징 데이터 도구와 리포트 포렌식 팩을 제공합니다.

Related MCP server: Apple Health MCP

설치

Python 3.11 이상을 사용하고 프로젝트 디렉터리에 가상 환경을 만들 것을 권장합니다:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

华为 내보내기 패키지는 번들링되거나 커밋되지 않으며, .gitignore는 모든 HUAWEI_HEALTH_* 디렉터리를 기본적으로 무시합니다.

로컬 확인

프로젝트 디렉터리에 HUAWEI_HEALTH_* 폴더가 하나만 있으면 자동으로 인식됩니다:

sport-health-inspect inspect
sport-health-inspect list

명시적으로 지정할 수도 있습니다:

sport-health-inspect --export-dir "D:\HealthData\HUAWEI_HEALTH_xxx" list

MCP Server 시작

로컬 Agent는 stdio를 권장합니다:

$env:SPORT_HEALTH_EXPORT_DIR="D:\HealthData\HUAWEI_HEALTH_xxx"
sport-health-mcp

MCP 클라이언트 설정의 핵심적인 형태는 다음과 같습니다. 실제 필드명은 클라이언트에 따라 다르므로 해당 클라이언트 문서를 기준으로 하세요:

{
  "mcpServers": {
    "sport-health": {
      "command": "C:\\sport-health-mcp\\.venv\\Scripts\\sport-health-mcp.exe",
      "env": {
        "SPORT_HEALTH_EXPORT_DIR": "D:\\HealthData\\HUAWEI_HEALTH_xxx"
      }
    }
  }
}

MCP 클라이언트에 등록

MCP stdio를 지원하는 클라이언트에 앞서 언급한 command와 env 설정을 추가하고 저장한 뒤 클라이언트를 재시작하세요. 클라이언트마다 설정 파일의 위치나 상위 필드명이 다를 수 있으므로 해당 클라이언트 문서를 따르세요.

여러 Agent에서 사용

• 같은 컴퓨터: MCP stdio를 지원하는 각 Agent는 같은 Server를 시작할 수 있지만, 해당 Agent의 설정 형식에 맞게 한 번 등록해야 합니다.

• 다른 사용자의 컴퓨터: 이 프로젝트를 설치하고 자신의 HUAWEI_HEALTH_* 데이터 패키지를 내보낸 뒤, 설정의 명령어와 데이터 디렉터리를 자신의 절대 경로로 바꾸세요.

• 웹 클라이언트나 cloud Agent: 사용자 컴퓨터의 로컬 stdio 프로세스에 접근할 수 없습니다. 이러한 클라이언트를 지원하려면 인증이 포함된 Streamable HTTP 배포를 별도로 제공하고, 암호화 업로드, 사용자 격리, 데이터 삭제, 개인정보 준수 체계도 함께 설계해야 합니다.

프로젝트는 작성자의 华为 데이터 패키지를 공유하지 않습니다. MCP Server는 범용적인 프로그램이며, 각 사용자의 데이터는 사용자 자신의 컴퓨터에 저장됩니다.

MCP 도구

• inspect_huawei_export: 데이터 패키지의 무결성을 검사합니다.

• list_activities: 운동 목록을 표시합니다.

• get_activity_summary: 단일 운동 요약을 조회합니다.

• get_activity_track: GPS 트랙을 페이지로 나누어 조회합니다.

• get_activity_samples: 심박수, 걸음 수, 속도, 고도 샘플을 페이지로 나누어 조회합니다.

• get_health_context: 운동 전후 여러 날의 건강 배경을 조회합니다.

• get_activity_environment: 과거 환경 데이터를 가져와 캐시합니다.

• get_report_evidence_pack: Agent가 리포트를 작성할 때 사용하는 결정적 증거 패키지를 생성합니다.

• get_report_contract: 고정된 리포트 구성, 길이, 작성 규칙을 가져옵니다.

Agent는 먼저 list_activities를 호출한 뒤 activity_id를 고르고, 우선적으로 get_report_evidence_pack을 호출하며, 반환된 report_contract를 엄격히 준수하는 것을 권장합니다. 고정된 형식에는 핵심 판단, 운동 성과 분석, 신체 반응, 훈련 조언만을 담고, 기기 앱이 이미 보여준 전체 지표를 되풀이하지 않아야 합니다. 원본 곡선이나 트랙을 봐야 할 때만 목록 상세 도구를 호출하세요.

테스트

테스트 프레임워크를 설치하지 않고 표준 라이브러리 테스트를 실행할 수 있습니다:

$env:PYTHONPATH="src"
python -m unittest discover -s tests -v

테스트는 코드로 만든 합성 운동 기록만 사용하며, 개인화된 내보내기 데이터에 의존하거나 포함하지 않습니다.

개인정보 보호 경계

• 원본 건강 데이터는 기본적으로 원격 자산인 컴퓨터에서만 읽습니다.

• 환경 보강 도구만 네트워크에 접속하며, 경로의 중심점과 날짜, 시간 범위만 전송합니다.

• MCP 도구는 읽기 전용이며, 华为 내보내기 파일을 수정하지 않습니다.

• 로그나 문제 보고서를 외부에 공개하기 전에, 좌표, 시간, 기기 식별자, 건강 지표를 반드시 제거해야 합니다.

• 소스 코드를 배포하기 전에 작업 디렉터리를 통째로 압축하지 마세요. 대신 버전 관리 내보내기나 빌드 아티팩트 배포로 게시하여, 이미 무시된 개인 데이터 디렉터리까지 패키징되지 않도록 하세요.

오픈소스 라이선스

이 프로젝트는 MIT License를 사용합니다. 보안 취약점을 보고하기 전에 SECURITY.md를 읽어 주시고, 참고 이슈에 실제 건강 데이터, GPS 트랙, 환경 캐시, 또는 로컬 경로가 포함된 로그를 업로드하지 마세요.

제3자 서비스 및 상표

• 환경 데이터는 Open-Meteo에서 제공되며, 데이터는 CC BY 4.0을 따릅니다. 표시할 때 출처와 라이선스를 반드시 표기해야 합니다.

• Open-Meteo의 무료 API는 비상업적 용도에만 사용할 수 있으며 호출 한도가 적용됩니다. 상업적 이용을 원한다면 공식 상업 인터페이스를 사용하거나 공식 라이선스에 따라 직접 구축하세요. 자세한 내용은 Open-Meteo Terms를 참고하세요.

• 이 프로젝트는 독립된 커뮤니티 프로젝트로, 华为 공식과는 재휴, 인가, 보증 관계가 없습니다. 관련 제품명과 상표는 각자 권리자에게 귀속됩니다.