로컬 에이전트 및 건강 컨텍스트

Health.md는 로컬 코딩 및 자동화 에이전트가 Apple Health 데이터를 다루는 두 가지 방법을 제공합니다.

명시적 터미널 명령 및 정규 추출을 위한 healthmd CLI
타입 지정 도구, 네이티브 시각화 및 승인된 생성 파일 내보내기를 위한 healthmd mcp serve와 MCP App

이식 가능한 MCP 서버는 포그라운드에 열린 iPhone과 직접 통신하며 Mac용 Health.md가 필요하지 않습니다. CLI는 원시/정규 내보내기에 동일한 직접 채널을 사용하거나 Mac 인덱스 워크플로에 Mac 앱의 루프백 API를 사용할 수 있습니다. HealthKit 읽기는 항상 iPhone에서 수행되며 healthmd.health_data v8은 공개 소스 계약으로 유지됩니다.

local agent -> healthmd mcp serve -> authenticated encrypted port 17647 -> foreground iPhone
local agent -> healthmd CLI -> direct iPhone or optional Mac loopback workflow

에이전트가 할 수 있는 작업

건강 값을 읽지 않고 직접 페어링 및 포그라운드 iPhone 준비 상태 확인
정규 측정 항목 ID 및 카테고리 목록 표시
iPhone에서 정확한 측정 항목, 소스, 날짜 및 세부 정보 범위 가져오기
정규 일별 문서 또는 소스 레코드 추출
증거 및 데이터 범위와 함께 타입 지정 측정 항목 계열 쿼리
안정적인 수면 세션 및 고정 수면 구간 생성
운동을 직전 및 직후 수면과 정렬
운동 목록 및 데이터 범위 확인
명시적 집계를 사용하여 정확한 기간 비교
사실 기반 훈련 증거 패킷 생성
제한된 요청을 사용하여 제한 없는 논리적 데이터 모음 페이지 순회
MCP Apps 안에서 측정 항목, 수면, 운동, 비교, 데이터 범위 및 증거 보기 렌더링
명시적인 기존 데스크톱 대상에 승인된 생성 파일 내보내기 실행
영속 내보내기 작업 확인, 재개 또는 취소

Health.md는 진단하거나, 치료를 권고하거나, 인과관계를 추론하거나, 결과를 건강함, 유해함, 더 나음 또는 더 나쁨으로 표시하지 않습니다.

로컬 도우미 설정

공개 미리보기 · 아직 검증된 안정 버전이 아님

크로스 플랫폼 패키지는 명시적으로 검증되지 않은 미리보기로 공개됩니다. 릴리스 증거에 명시된 정확한 모바일 빌드를 사용하세요. 서명된 Mac 도우미는 에이전트 구성에서 계속 사용할 수 있습니다.

macOS 또는 Linux에서 brew install CodyBontecou/tap/healthmd를 실행한 다음 healthmd --version을 확인합니다.
healthmd setup codex를 실행합니다. Codex를 구성하고 아직 신뢰된 iPhone이 없으면 페어링을 엽니다.
iPhone의 Health.md에서 Direct CLI 액세스 페어링을 완료하고 앱을 포그라운드에 유지합니다.
Claude 또는 수동 호스트 설정의 경우 Health.md MCP 서버 및 App을 사용하여 절대 healthmd 경로와 인수 mcp serve를 구성합니다.
설정에서 구성이 변경되었다고 보고하면 호스트를 다시 시작한 뒤 healthmd_doctor를 호출합니다.

에이전트 스킬 설치

Health.md Mac 앱은 Mac 사용자를 위한 선택적 설치 및 스킬 배포 경로이며 이식 가능한 MCP의 의존성이 아닙니다.

대부분의 사용자는 skills.sh의 소비자용 Health.md CLI 스킬만 설치해야 합니다.

npx skills add CodyBontecou/health-md@healthmd-cli

공개 저장소는 작업별 스킬 4개를 제공합니다.

스킬	용도
`healthmd-cli`	사용자가 승인한 범위 내의 CLI/MCP 쿼리 및 내보내기
`healthmd-cli-operator`	직접 iPhone 작업 및 영속 작업 복구
`healthmd-cli-development`	CLI, MCP, 프로토콜 및 iPhone 서비스 개발
`healthmd-cli-qa`	자동화된 검증 및 실제 기기 검증

기여자용 스킬을 설치하려면 @ 뒤의 이름을 바꾸세요. 일반적인 건강 데이터 요청에는 개발 또는 QA 지침을 설치하지 마세요. npx skills add CodyBontecou/health-md --list를 사용하면 스킬을 설치하지 않고 저장소를 확인할 수 있고, npx skills update healthmd-cli --project --yes를 사용하면 프로젝트 범위 소비자 스킬을 업데이트할 수 있습니다. 모든 명령과 게시 계약은 저장소 설치 가이드에 설명되어 있습니다.

스킬은 지침 모음입니다. healthmd 또는 healthmd-mcp를 설치하거나 MCP를 구성하거나 휴대폰을 페어링하거나 건강 데이터 접근 권한을 부여하지 않으며 자동으로 업데이트되지도 않습니다. 설치 전에 소스를 검토하세요.

앱의 스킬 설치 프로그램은 승인한 디렉터리에 healthmd-cli/SKILL.md를 만듭니다. Health.md 자체 스킬 폴더만 대체합니다. 이 스킬은 제한된 명령, 구조화된 결과 처리, 개인정보 보호 규칙, 모델 공급자 공개 경계 및 결과를 알 수 없을 때의 안전한 복구를 안내합니다.

에이전트가 심볼릭 링크를 만들게 하려면 Mac 앱의 설정 프롬프트를 사용하세요. Health.md 자체는 셸 시작 파일 또는 /usr/local/bin을 암묵적으로 수정하지 않습니다.

준비 상태 우선

이식 가능한 MCP 클라이언트에서는 healthmd_doctor를 호출하세요. 건강 값을 읽지 않고 로컬 직접 신뢰와 연결된 포그라운드 iPhone을 확인하며, 건강 데이터가 포함되지 않은 실행 가능한 오류를 반환합니다. 각 타입 지정 MCP 쿼리는 해당 iPhone에 보내는 명시적인 새 요청입니다. 요청한 범위만 캡처하고 기기에서 타입 지정 쿼리를 평가한 뒤 제한된 페이지를 반환합니다.

Mac 루프백 CLI 사용자는 계속 healthmd doctor를 실행하여 healthmd.cli_doctor v1 준비 상태, 암호화 컨텍스트 데이터 범위 및 다음 조치를 확인할 수 있습니다.

모든 요청에 자체 범위 포함

Health.md는 저장된 액세스 프로필, 호출자 등록, 권한 부여 레코드 또는 CLI 자격 증명을 사용하지 않습니다. 각 요청은 필요한 전체 데이터 범위를 제공합니다.

측정 항목 ID 또는 카테고리
Apple Health 및 선택적 제공자 소스 선택자
정확한 날짜 또는 사용 가능한 모든 날짜
요약 또는 무손실 세부 정보
쿼리 작업
제한된 페이지 제어

새 가져오기는 현재 카탈로그를 기준으로 범위를 검증하고 영속 작업과 함께 저장하며, 저장된 내보내기 환경설정을 변경하지 않고 iPhone에 적용합니다.

명시적 가져오기 선택이 없는 요청은 사용자의 일반 내보내기 설정을 상속하지 않고 거부됩니다.

권한 부여 경계

이식 가능한 MCP는 페어링된 직접 프로토콜을 사용합니다. 네이티브 자격 증명 저장소, 상호 트랜스크립트 인증, 암호화 패킷, 재생 보호 및 컴퓨터의 명시적 주소로 연결되는 포그라운드 iPhone을 포함합니다. 선택적 Mac 쿼리 API는 IPv4 및 IPv6 루프백에서만 수신하고 피어가 루프백인지 검증합니다.

선택적 Mac 루프백 모드에서는 Health.md가 열려 있는 동안 포트 17645에 접근할 수 있는 모든 로컬 프로세스가 동일한 쿼리 요청을 실행할 수 있습니다. 로컬 컴퓨터 액세스를 쿼리 권한으로 취급하세요.

포트를 LAN 인터페이스에 바인딩하거나 프록시하지 마세요.
다른 컴퓨터로 터널링하지 마세요.
앞에 HTTP 역방향 프록시를 두지 마세요.
루프백이 아닌 URL로 MCP를 구성하지 마세요.
도우미를 실행할 수 있는 로컬 에이전트를 검토하세요.

이전 프로필 및 활동 라우트는 호환성을 위해 410 removed_endpoint를 반환합니다.

정규 데이터 및 파생 보기

에이전트에 소스 형태 데이터나 검증된 대용량 원시/정규 본문이 필요하면 healthmd extract를 사용하세요.

healthmd extract --metric workouts --last 14 \
  --object records --detail lossless --output workout-records.json

파생 보기 및 호스트 내 시각화에는 쿼리 명령 또는 MCP 도구를 사용하세요.

healthmd query --metric resting_heart_rate --last 30 --all-pages
healthmd sleep sessions --last-nights 14 --window first:4h
healthmd training align --last 14 --workout running --sleep-window first:4h

두 역할은 의도적으로 구분됩니다.

인터페이스	계약 역할
`healthmd.health_data` v8	공개 일별 소스 문서
`healthmd.healthkit_records` v1	무손실 일별 문서 안의 정규 소스 레코드 아카이브
`healthmd.extract_receipt`	추출 범위 및 완료 메타데이터
`healthmd.query_context_day` v1	폐기 가능한 암호화 인덱스 레코드
`healthmd.query_response` v1	타입이 지정되고 페이지로 나뉜 파생 결과
`healthmd.evidence_packet` v1	소스 증거에 연결된 사실 기반 패킷
작업 및 순회 수신 확인	전송, 영속성 및 완료 메타데이터

프로젝션 또는 타입이 지정된 결과는 완전한 일별 소스 문서로 가장하지 않습니다.

새 데이터 가져오기

고수준 쿼리는 기본적으로 새 데이터를 가져옵니다.

healthmd query --category Sleep --last 14

Health.md는 전용 암호화 컨텍스트 요청을 만듭니다. 내보내기 파일을 쓰거나 파일 내보내기 할당량을 사용하지 않습니다. iPhone은 명시적 범위를 읽고 결정론적 압축 소유자 날짜를 만들며 제한되고 재개 가능한 파티션을 전송합니다. Mac은 암호화된 각 날짜를 커밋한 뒤 확인합니다.

새 완료 확인은 요청한 각 측정 항목, 소스 또는 제공자 및 소유자 날짜를 새로 고침 시작 후 대체된 블롭과 비교합니다. 이전 캐시 값과 다른 제공자의 데이터가 실패한 가져오기를 숨길 수 없습니다.

제공자 전용 요청은 HealthKit을 건너뛸 수 있습니다. 제공자 기록 순회는 고정된 전체 결과 제한을 적용하지 않고 제공자 고유 커서를 따릅니다.

암호화된 Mac 컨텍스트

Mac은 소유자 날짜마다 독립적으로 암호화된 세대 하나를 저장합니다. 임의의 256비트 키는 이 기기 전용이자 잠금 해제 시 사용 가능한 항목으로 키체인에 저장됩니다.

날짜 블롭과 매니페스트는 AES-256-GCM을 사용합니다.
파일 이름은 날짜나 측정 항목 이름이 아닌 임의 UUID입니다.
소유자 날짜와 인덱스 항목은 암호화됩니다.
파일에는 소유자 전용 권한과 백업 제외가 적용됩니다.
커밋은 암호화된 매니페스트를 대체하기 전에 변경 불가능한 새 세대를 기록합니다.
키 누락, 인증 실패, 잘못된 날짜 또는 매니페스트 불일치 시 읽기는 안전하게 실패합니다.

저장소에는 구성된 전체 측정 항목, 날짜, 기록 또는 결과 제한이 없습니다. 명령은 한 번에 하루씩 복호화하고 결과를 페이지로 나누므로 제한됩니다.

인덱스는 폐기할 수 있습니다. 정규 내보내기가 데이터의 기준입니다.

보존 및 삭제

Health.md는 암묵적 보존 일정에 따라 쿼리 컨텍스트를 삭제하지 않습니다. Mac 설정에는 저장된 소유자 날짜 수와 날짜 범위가 표시됩니다.

다음을 사용하세요.

이전 컨텍스트 삭제: 선택한 경계보다 엄격히 이전인 소유자 날짜 제거
모든 암호화 컨텍스트 삭제: 모든 암호화 세대와 전용 키체인 키 제거

키 또는 암호문이 손상되어도 전체 삭제를 사용할 수 있습니다. 키를 제거하면 삭제되지 않은 암호문 잔여물도 암호학적으로 삭제됩니다.

쿼리 컨텍스트를 삭제해도 내보내기 파일, 연결된 제공자 자격 증명 또는 Apple Health 데이터는 삭제되지 않습니다.

타입 지정 값 및 누락 상태

쿼리 값에는 타입 태그가 지정됩니다. 결과는 수량과 정규 단위, 기간, 부호 있는 개수, 문자열, 카테고리, Boolean, UTC 타임스탬프, 달력 날짜, 중첩 배열 또는 알 수 없는 향후 타입 지정 페이로드를 전달할 수 있습니다.

누락 데이터는 명시적으로 유지됩니다.

complete_empty: 표현된 범위에 일치하는 관측값이 없음
partial: 요청 범위의 일부만 완료됨
failed, unsupported, skipped, cancelled: 각 의미를 유지
not_requested, legacy_unavailable, redacted, not_synchronized: 서로 구분

Health.md는 없는 값을 숫자 0으로 변환하지 않습니다. 실제 0은 사용 가능한 타입 지정 값으로 인코딩됩니다.

증거 및 중립적 표현

결과는 다음과 같은 소스 증거에 사실을 연결합니다.

일별 요약 키
정규 HealthKit UUID
외부 식별 정보
쿼리 매니페스트 결과
무결성 경고
부분 실패

증거 확인은 증거 ID, 로케이터, 소스 스키마, 소스 버전 및 소스 다이제스트를 함께 검사합니다.

기간 비교 방향은 increased, decreased, unchanged 또는 not_comparable로 제한됩니다. 훈련 정렬은 인과 효과가 아니라 타임스탬프와 간격을 보고합니다. 증거 패킷은 의학적 결론이 아니라 저장된 관측값과 데이터 범위를 보고합니다.

에이전트는 자체 답변에서도 이러한 한계를 지켜야 합니다. 데이터 누락을 밝히고, 상관관계를 인과관계로 바꾸지 않으며, 의학적 질문은 자격을 갖춘 임상의에게 안내해야 합니다.

제한된 페이지, 완전한 논리적 액세스

쿼리 페이지는 max_items, max_bytes 및 불투명한 next_cursor를 사용합니다. 저장된 전체 날짜, 운동, 측정 항목 또는 결과 항목에 대한 계약 수준 제한은 없습니다.

커서는 무결성이 보호되며 의미적 쿼리와 암호화된 데이터 모음의 리비전에 연결됩니다. Health.md는 다음을 거부합니다.

수정된 커서
다른 쿼리에 사용된 커서
데이터 모음이 변경되기 전에 발급된 커서
자동 순회 중 반복된 커서

제한된 자동 순회에는 --all-pages 또는 MCP all_pages: true를 사용하세요. 호출 하나가 전체 안전 한도에 도달하면 범위를 좁히거나 수동으로 페이지를 탐색하세요.

에이전트 보고 체크리스트

결과를 요약할 때 다음을 보고하세요.

사용한 명령 또는 도구
정확한 요청 날짜, 측정 항목, 소스 및 세부 정보
새 데이터, 캐시 또는 데이터 범위 재사용 모드
요청 범위 상태와 데이터 모음 상태를 별도로
페이지 또는 순회 완료 여부
언급한 값의 단위 및 소스 증거
누락 구간, 제한 사항 및 관련 없는 건너뜀
작업이 일시 중지되었거나 재개 가능한 경우 작업 ID

사용자가 해당 값을 명시적으로 요청하고 민감 정보 노출 범위를 이해하지 않는 한 원시 레코드, 경로, 임상 텍스트, 약물 세부 정보, 기분 항목 또는 첨부 파일을 포함하지 마세요.