---

name: boltz2-predict version: 1.1.0 description: | Boltz-2 단백질 구조 예측 자동화 스킬. 시퀀스 또는 구조 파일을 입력받아 업로드 → spec 생성 → 검증 → 잡 제출 → 상태 추적까지 전체 워크플로를 자동화한다. 나노바디-타겟 cross-model workflow (boltzgen → Boltz-2) 도 지원. Use when asked to "구조 예측", "structure prediction", "boltz2 실행", "단백질 복합체 예측", "나노바디 구조 예측", "docking prediction". allowed-tools:

• Bash
• Read
• Write
• Agent

---

/boltz2-predict

Boltz-2 MCP 서버를 통해 단백질 구조 예측 잡을 제출하는 스킬.

설치

git clone https://github.com/SungminKo-smko/boltz2_skill ~/.claude/skills/boltz2-predict

MCP 서버 확인 (run first)

claude mcp list 2>/dev/null | grep boltz2 || echo "NOT_REGISTERED"

NOT_REGISTERED 출력 시 — Streamable HTTP MCP 등록:

claude mcp add boltz2 --transport http https://boltz2-api.politebay-55ff119b.westus3.azurecontainerapps.io/mcp/mcp

OAuth 2.1 인증: HTTP 전송 모드를 사용하면 첫 연결 시 브라우저가 열리며 Google OAuth 로그인이 진행됩니다. @shaperon.com 계정으로 로그인하면 인증이 자동 완료됩니다.

또는 로컬 stdio 모드 (개발용):

cd ~/workspace/boltz2_MSA && source .venv/bin/activate
claude mcp add boltz2 python3 -m boltz2_service.mcp.stdio

Step 0: 인증 확인

OAuth 2.1 자동 인증 (기본): MCP 서버가 --transport http (streamable-http)로 등록되어 있으면 OAuth 2.1 토큰이 자동으로 관리됩니다. 별도의 api_key 파라미터 없이 모든 도구를 즉시 사용할 수 있습니다.

MCP가 HTTP 모드로 등록되어 있는지 확인:

claude mcp list 2>/dev/null | grep boltz2 || echo "NOT_REGISTERED"

• HTTP 모드로 등록됨 → 인증 완료. api_key 파라미터 생략 가능. Step 1로 바로 이동.
• NOT_REGISTERED → 아래 명령으로 등록:

  claude mcp add boltz2 --transport http https://boltz2-api.politebay-55ff119b.westus3.azurecontainerapps.io/mcp/mcp
  

Fallback: .env 파일의 API_KEY (선택사항)

OAuth를 사용할 수 없는 환경(로컬 stdio 모드 등)에서만 필요합니다.

SKILL_ENV="$HOME/.claude/skills/boltz2-predict/.env"
BOLTZ2_API_KEY=""

if [ -f "$SKILL_ENV" ]; then
    BOLTZ2_API_KEY=$(grep -E "^API_KEY=" "$SKILL_ENV" | cut -d= -f2-)
fi

[ -z "$BOLTZ2_API_KEY" ] && BOLTZ2_API_KEY="${BOLTZ2_API_KEY:-${API_KEY:-}}"

• 값이 있으면 → tool 호출 시 api_key 인수로 전달
• 값이 없고 stdio 모드 → get_my_api_key() 호출로 발급 시도 후 .env에 저장
• MCP 미등록 → HTTP 모드 등록을 권장:

  claude mcp add boltz2 --transport http https://boltz2-api.politebay-55ff119b.westus3.azurecontainerapps.io/mcp/mcp

Step 1: 입력 모드 판별

사용자 입력을 분석하여 3가지 모드 중 하나를 선택:

모드 A: 시퀀스 기반 예측 (가장 일반적)

• 사용자가 아미노산 시퀀스를 직접 제공한 경우
• FASTA 형식이거나 raw 시퀀스
• → Step 3A로 이동

모드 B: 구조 파일 기반 예측

• 사용자가 .cif 또는 .pdb 파일을 제공한 경우
• → Step 2로 이동 (파일 업로드 필요)

모드 C: 나노바디-타겟 Cross-Model Workflow

• 사용자가 나노바디 시퀀스 + 타겟 구조를 모두 제공한 경우
• 또는 "나노바디 구조 예측", "nanobody docking" 등 키워드
• → Step 2 (타겟 업로드) → Step 3C로 이동

요구사항 수집

사용자가 이미 정보를 제공했으면 묻지 않고 바로 진행.

모드 A 필수:

1. 단백질 시퀀스 (1개 이상)
2. 각 체인 ID (기본: A, B, C...)

모드 B 필수:

1. 구조 파일 경로 (.cif 또는 .pdb)
2. 추가 sequence (선택 — 단백질 시퀀스, 리간드 SMILES 등)

모드 C 필수:

1. 나노바디 시퀀스
2. 타겟 구조 파일 경로 또는 asset_id

공통 선택:

• prediction_type — structure (기본), affinity, structure+affinity
• diffusion_samples — 기본 1 (1-1000, 100 이상은 앙상블 예측용)
• output_format — mmcif (기본) 또는 pdb

Step 2: 구조 파일 업로드 (모드 B, C만)

절대 금지: base64 인코딩, Read로 파일 내용 읽기 — 컨텍스트 초과 유발. create_upload_url로 SAS URL을 받아 curl로 직접 업로드한다.

Claude Desktop 감지

if [ -d "/mnt/user-data/uploads" ]; then
    echo "CLAUDE_DESKTOP=true"
    ls /mnt/user-data/uploads/
else
    echo "CLAUDE_DESKTOP=false"
fi

업로드

create_upload_url(
    filename="<파일명>"
    # api_key="<BOLTZ2_API_KEY>"  # OAuth 연결 시 생략 가능
)
# → asset_id, upload_url, content_type, curl_hint

반환된 curl_hint의 <FILE_PATH>를 실제 경로로 교체 후 Bash 실행:

curl -s -X PUT -T "<절대경로>" \
  -H "x-ms-blob-type: BlockBlob" \
  -H "Content-Type: <content_type>" \
  "<upload_url>"

Step 3A: 시퀀스 기반 Spec 생성 + 잡 제출

YAML spec을 직접 생성하여 검증 + 제출:

validate_spec(
    raw_yaml="""version: 1
sequences:
  - protein:
      id: A
      sequence: <시퀀스1>
  - protein:
      id: B
      sequence: <시퀀스2>
""",
    asset_ids=[]
    # api_key="<BOLTZ2_API_KEY>"  # OAuth 연결 시 생략 가능
)
# → spec_id (valid=True 일 때)

검증 성공 시:

submit_job(
    spec_id="<spec_id>",
    prediction_type="structure",
    diffusion_samples=1
    # api_key="<BOLTZ2_API_KEY>"  # OAuth 연결 시 생략 가능
)
# → job_id

검증 실패 시:

• errors 내용을 사용자에게 보여주고 수정 안내
• 서버에 boltz 바이너리가 없으면 503 반환 — 이 경우 검증을 건너뛰고 raw spec으로 직접 제출 불가. 사용자에게 알린다.

Step 3B: 구조 파일 기반 Spec 생성

템플릿 렌더링 (권장)

render_template(
    target_asset_id="<asset_id>",
    additional_sequences=[
        {"protein": {"id": "B", "sequence": "<추가 시퀀스>"}},
        # {"ligand": {"id": "L", "smiles": "CCO"}}  # 리간드 추가 시
    ],
    constraints=[]  # 선택
    # api_key="<BOLTZ2_API_KEY>"  # OAuth 연결 시 생략 가능
)
# → spec_id, canonical_yaml

Raw YAML (복잡한 케이스)

validate_spec(
    raw_yaml="<yaml 문자열>",
    asset_ids=["<asset_id>"]
    # api_key="<BOLTZ2_API_KEY>"  # OAuth 연결 시 생략 가능
)

이후 submit_job으로 제출.

Step 3C: 나노바디-타겟 Cross-Model Workflow

boltzgen에서 디자인한 나노바디 시퀀스를 Boltz-2로 구조 예측:

submit_nanobody_structure_prediction(
    nanobody_sequence="<나노바디 시퀀스>",
    target_asset_id="<타겟 asset_id>",
    nanobody_chain_id="N",
    prediction_type="structure",
    diffusion_samples=1
    # api_key="<BOLTZ2_API_KEY>"  # OAuth 연결 시 생략 가능
)
# → job_id, spec_id, status, spec_yaml

이 도구는 spec 생성 + 검증 + 제출을 한 번에 처리한다.

Step 4: 상태 확인

잡 제출 후 바로 상태를 확인하고, running 상태이면 정보를 출력한다:

get_job(job_id="<job_id>")
# api_key는 OAuth 연결 시 생략 가능

출력 예시:

잡 제출 완료!
- Job ID: abc-123-def
- Status: queued → running 대기 중
- 예상 소요시간: 구조 크기에 따라 10분~수 시간 (타임아웃 없음)

상태 확인: get_job(job_id="abc-123-def")
결과 다운로드: get_artifacts(job_id="abc-123-def") (succeeded 후)

Step 5: 결과 확인 및 다운로드

사용자가 결과를 요청하면:

get_job(job_id="<job_id>")
# api_key는 OAuth 연결 시 생략 가능

• status == "succeeded" 이면:

get_artifacts(job_id="<job_id>")
# → artifacts: {filename: download_url, ...}
# api_key는 OAuth 연결 시 생략 가능

다운로드 URL을 사용자에게 제공하거나, Bash로 다운로드:

curl -o results.zip "<download_url>"

• status == "failed" 이면: failure_code, failure_message 출력
• status == "running" 이면: progress_percent, current_stage 출력

잡 관리 도구

# OAuth 연결 시 api_key 생략 가능 (모든 도구 공통)
get_job(job_id)                               # 상태 확인
get_logs(job_id, tail=100)                    # 진행 상황 + 로그
list_jobs(status="running")                   # 잡 목록
cancel_job(job_id)                            # 잡 취소
list_templates()                              # 템플릿 목록
list_workers()                                # 워커 상태

공개 URL (인증 불필요)

MCP 도구 대신 공개 URL로 로그와 상태를 확인할 수 있다. 브라우저에서 직접 열거나 외부 공유 시 활용:

• 로그 스트리밍: https://boltz2-api.politebay-55ff119b.westus3.azurecontainerapps.io/v1/boltz2/prediction-jobs/<job_id>/logs/public?tail=200
• 로그 텍스트: https://boltz2-api.politebay-55ff119b.westus3.azurecontainerapps.io/v1/boltz2/prediction-jobs/<job_id>/logs/public/text?tail=50
• 상태 조회: https://boltz2-api.politebay-55ff119b.westus3.azurecontainerapps.io/v1/boltz2/prediction-jobs/<job_id>/status/public

이메일 알림

잡 상태 변경(queued → running → succeeded/failed) 및 단계 전환 시 Gmail SMTP를 통해 자동으로 이메일 알림이 발송된다. 별도 설정 불필요.

Boltz-2 YAML Spec 레퍼런스

기본 구조 (v1)

version: 1
sequences:
  - protein:
      id: A
      sequence: MKTL...
  - protein:
      id: B
      sequence: EVQL...

Entity 타입

protein — 아미노산 시퀀스

- protein:
    id: A                    # 체인 ID (필수)
    sequence: MKTLLILAVL...  # 1-letter 아미노산 시퀀스 (필수)

cif — 기존 구조 파일

- cif:
    path: targets/input.cif  # 업로드된 파일 경로

ligand — 소분자 (SMILES 또는 CCD 코드)

- ligand:
    id: L
    smiles: 'CCO'           # SMILES 표기
    # ccd: ATP               # 또는 CCD 코드

Constraints (선택)

constraints:
  - bond:
      atom1: [A, 1, CA]     # [chain, residue, atom]
      atom2: [B, 50, CA]

prediction_type 옵션

| 값 | 설명 | |----|------| | structure | 기본 구조 예측 | | affinity | 결합 친화도 예측 | | structure+affinity | 구조 + 친화도 동시 | | virtual_screening | 가상 스크리닝 |

runtime_options 주요 파라미터

| 파라미터 | 기본값 | 범위 | 설명 | |----------|--------|------|------| | diffusion_samples | 1 | 1-1000 | 디퓨전 샘플 수 (많을수록 다양한 구조, 100+ 앙상블) | | max_parallel_samples | 5 | 1-100 | GPU에서 동시 처리할 샘플 수 (OOM 시 낮춤) | | sampling_steps | 200 | 50-1000 | 샘플링 스텝 | | recycling_steps | 3 | 1-10 | 리사이클링 스텝 | | output_format | mmcif | pdb/mmcif | 출력 형식 | | use_msa_server | true | - | MSA 서버 사용 여부 | | use_potentials | false | - | 에너지 기반 가이드 |

BoltzGen 통합 (Cross-Service)

boltz2와 boltzgen은 동일한 Supabase 인증 시스템(nanomapAIDEN 프로젝트)을 공유한다. boltz2 API KEY를 이미 발급받은 사용자는 동일한 로그인(/auth/login, /auth/callback, /auth/device-code)으로 boltzgen용 KEY도 별도 발급받을 수 있다.

• 두 서비스 모두 b2_ 접두사를 사용하지만 KEY는 서비스별로 분리됨
• boltz2 KEY는 boltz2에서만, boltzgen KEY는 boltzgen에서만 유효
• 인증 엔드포인트 패턴은 동일: /auth/login, /auth/callback, /auth/device-code

오류 처리

• 인증 실패 (OAuth): MCP가 HTTP 모드로 등록되어 있는지 확인. 브라우저 OAuth 로그인 재시도.
• API_KEY 미설정 (fallback): OAuth를 사용할 수 없는 환경에서만 해당. ~/.claude/skills/boltz2-predict/.env에 API_KEY=<key> 추가
• MCP 미등록: claude mcp add boltz2 --transport http <URL> 실행
• 503 boltz2 binary not available: 서버에 boltz 바이너리가 설치되지 않음. 검증 불가.
• 401 인증 실패: API KEY 확인
• 429 Rate limit: 일일 한도(20) 또는 동시 한도(5) 초과
• 잡 실패: get_job의 failure_code 확인
  • boltz2_run_failed — Boltz-2 실행 오류
  • worker_timeout — 워커 heartbeat 없음 (list_workers로 상태 확인)

API 엔드포인트 (REST 직접 호출 시)

Base URL: https://boltz2-api.politebay-55ff119b.westus3.azurecontainerapps.io

| Method | Path | 설명 | |--------|------|------| | GET | /healthz | 헬스체크 | | GET | /auth/login | Google OAuth 시작 | | POST | /auth/device-code | Device Auth 코드 발급 | | POST | /v1/boltz2/uploads | 업로드 URL 생성 | | GET | /v1/boltz2/spec-templates | 템플릿 목록 | | POST | /v1/boltz2/spec-templates/render | Spec 렌더링 | | POST | /v1/boltz2/specs/validate | Spec 검증 | | POST | /v1/boltz2/prediction-jobs | 잡 제출 | | GET | /v1/boltz2/prediction-jobs | 잡 목록 | | GET | /v1/boltz2/prediction-jobs/{id} | 잡 상세 | | POST | /v1/boltz2/prediction-jobs/{id}:cancel | 잡 취소 | | GET | /v1/boltz2/prediction-jobs/{id}/artifacts | 결과 다운로드 | | GET | /v1/boltz2/prediction-jobs/{id}/logs/public | 공개 로그 스트리밍 (인증 불필요) | | GET | /v1/boltz2/prediction-jobs/{id}/logs/public/text | 공개 로그 텍스트 (인증 불필요) | | GET | /v1/boltz2/prediction-jobs/{id}/status/public | 공개 상태 조회 (인증 불필요) | | GET | /docs | Swagger UI |