protein-mcp-server

공개 호스팅 서버: https://protein.caseyjhand.com/mcp

도구

구조 연구의 전체 흐름을 아우르는 일곱 가지 도구 — 탐색, 조회, 상동체 검색, 리간드 추적, 비교, 코퍼스 프로파일링, 주석 — 실험(PDB) 및 예측(AlphaFold) 구조를 하나의 인터페이스에서 제공합니다:

protein_search_structures

RCSB Search v2를 통한 실험(PDB) 및 예측(계산 모델) 구조 간 연합 검색.

• 자유 텍스트, 단백질 서열(mmseqs2 유사성 검색 트리거), 생물체/방법/해상도 필터

• content_type은 검색 범위를 experimental, predicted, 또는 all로 한정합니다 — 기본값 all은 두 세계의 진정한 합집합이므로 계산 모델이 PDB 항목과 함께 표시됩니다

• 모든 결과는 source를 명시합니다; 실험 결과는 제목, 방법, 해상도, 생물체 정보가 보강되고, 계산 모델은 ID에서 파싱된 UniProt 접근 번호를 포함합니다

• 선택적 facets는 추가 호출 없이 결과와 함께 방법/생물체/출시 연도 분석을 반환하며, 각 차원에 대해 값이 없는 일치 항목 수를 보고합니다; 각 차원은 한 번만 나열될 수 있습니다

• 체인 히트 ID를 protein_get_structure에 직접 전달할 수 있습니다

protein_get_structure

메타데이터와 좌표 파일 URL로 구조를 조회하며, source에 따라 제공자를 결정합니다.

• source: experimental은 PDB 항목 ID를 받아 하나의 RCSB GraphQL 호출로 배치 처리합니다; 또한 검색이 반환하는 계산 모델 ID(AF_* / MA_*)도 해석하며, 이들은 해당 모델링 제공자에 귀속된 source: predicted로 반환됩니다

• source: predicted는 UniProt 접근 번호를 받아 pLDDT/PAE 신뢰도를 포함한 AlphaFold 모델을 반환합니다

• source: best_available은 UniProt 접근 번호를 받아 최적 연합 모델(실험 모델이 있으면 그것, 없으면 최상의 예측)을 반환합니다

• ID별 부분 성공 — 해석되지 않은 ID는 배치 수준 오류가 아닌 failed[]에 나열됩니다

• include_coords는 좌표 내용을 인라인합니다; 배치가 응답 예산을 초과하면 구조별 크기 개요를 반환하므로 특정 구조에 대해 sections: [ids]로 다시 호출할 수 있습니다

• 모든 응답은 업스트림 데이터 라이선스와 인용을 명시하는 attribution 블록을 포함합니다 (업스트림 데이터 라이선스 참조)

protein_find_similar

서열 또는 폴드 기준으로 구조적 또는 진화적으로 관련된 단백질을 찾습니다.

• by: sequence는 동기식 RCSB mmseqs2 검색을 실행합니다; by: structure는 실험 및 예측 데이터베이스에 대해 비동기식 Foldseek 검색을 실행합니다

• 원시 한 글자 서열, PDB ID, 또는 UniProt 접근 번호로 질의할 수 있습니다

• Foldseek 대상은 기본적으로 pdb100 + afdb50입니다; databases로 재정의할 수 있습니다(예: afdb-swissprot, BFVD)

• 폴링 예산을 초과하는 비동기 작업은 ticketId와 함께 status: computing을 반환합니다 — 동일한 작업을 다시 제출하는 대신 ticket_id에 해당 값을 설정하여 다시 호출하면 같은 작업을 폴링합니다

• 각 결과는 출처 엔진과 원본 데이터베이스를 명시합니다

protein_track_ligands

PDB 전반에 걸친 리간드 발견 및 결합 부위 분석.

• mode: find_ligand는 이름 또는 화학식을 화학식, 분자량, SMILES, InChIKey가 포함된 화학 컴포넌트 ID로 해석합니다

• mode: structures_with_ligand는 정확한 컴포넌트 ID로 리간드를 포함하는 PDB 항목을 반환합니다

• mode: binding_site는 구조에서 리간드 포켓을 둘러싼 단백질 잔기를 접촉 거리와 함께 반환합니다

• 결합 부위는 실험 전용입니다 — 기탁된 좌표에서 계산됩니다(예측 모델에는 결합 리간드가 없음)

protein_compare_structures

RCSB 구조 비교 서비스를 통한 여러 구조(구성된 PROTEIN_MAX_COMPARE_STRUCTURES 상한까지)의 구조 정렬.

• 방법: tm-align, fatcat-rigid, fatcat-flexible

• reference: first는 모든 구조를 첫 번째 구조에 정렬합니다; reference: all_pairs는 전체 쌍별 행렬을 계산합니다

• 선택적 구조별 chain은 정렬을 단일 체인으로 제한합니다

• structures[]에 반복된 구조는 한 번만 비교됩니다 — 반복은 자기 정렬과 대칭 쌍만 추가할 뿐이며, 재개 메커니즘이 원본과 구분할 수 없습니다

• 각 쌍은 독립적인 비동기 작업으로, 동시성 상한과 쌍별 부분 성공으로 확장됩니다 — 예산이 소진될 때까지 계산 중인 쌍은 해당 작업 uuid와 함께 status: computing을 반환하고, 실패한 쌍은 다른 쌍에 영향을 주지 않고 해당 행만 저하시킵니다

• 이전 응답의 pairs[]에서 복사한 일치하는 { a, b, uuid } 항목을 resume[]에 포함하여 다시 호출하면 재제출 대신 계산 중인 쌍의 작업을 폴링합니다

• 쌍별로 TM-score, RMSD, 정렬된 잔기 수를 반환하며, modeledResidues와 coverage도 포함합니다 — 각각 [a, b] 튜플이며, coverage는 해당 구조 자체의 모델링된 잔기 수 대비 0–100 백분율입니다

protein_analyze_collection

선택적 범위 질의에 대해 PDB를 분포와 추세로 프로파일링합니다 — RCSB의 서버 측 패싯 엔진 기반(단일 호출, 압축된 버킷, 행 풀 없음).

• method, organism, polymer_type, resolution, release_year, 또는 molecular_weight로 그룹화

• 분석에는 group_by 차원 하나, 교차 분석에는 서로 다른 차원 두 개(첫 번째가 두 번째를 중첩)를 사용합니다; 반복된 차원은 거부됩니다

• interval은 값 히스토그램의 빈 너비 또는 날짜 히스토그램의 기간(year / month / quarter)을 설정합니다

• 자유 텍스트 query, organism, method, 또는 max_resolution으로 범위를 한정합니다; content_type은 구조 세계를 선택합니다

• bucket_limit은 응답이 아닌 차원 수준별 버킷 수를 제한합니다 — 교차 분석에서는 상위 차원과 각 상위 버킷 내 중첩 하위 차원에 별도로 적용되므로 최대 bucket_limit × (1 + bucket_limit)개의 버킷이 반환됩니다. 각 수준은 자체 잘림을 표시하고, bucketsReturned는 실제 총계를 제공합니다

• 모든 차원은 missingValueCount를 보고합니다 — 범위 내에서 해당 속성에 값이 없어 어떤 버킷에도 속하지 않는 일치 항목입니다(resolution 분석은 NMR 항목을 포함하지 않으며, method와 resolution 모두 계산 모델을 포함하지 않습니다)

protein_get_annotations

단백질의 서열 및 기능 주석.

• UniProt 기능(도메인, 결합 부위, PTM) 및 자연 서열 변이

• GO 용어가 포함된 InterPro 도메인/패밀리 소속(Pfam, PROSITE, …)

• UniProt 접근 번호를 직접 제공하거나 PDB ID를 제공할 수 있습니다 — 구조의 서열 교차 참조를 통해 UniProt 접근 번호로 해석됩니다

• 다중 체인 PDB 항목은 여러 접근 번호에 매핑될 수 있습니다; 기본값은 결정론적 최저 저자 체인 선택이며, 대안은 ambiguity 아래에 나열됩니다. 특정 체인을 선택하려면 chain(저자 체인 ID, 예: A)을 전달하세요

• include는 가져올 주석 클래스를 한정합니다: features, domains, variants, 또는 all

• 모든 응답은 업스트림 데이터 라이선스와 인용을 명시하는 attribution 블록을 포함합니다 (업스트림 데이터 라이선스 참조)

Related MCP server: UniProt MCP Server

리소스

모든 리소스 데이터는 도구를 통해서도 접근할 수 있습니다 — pdb://{entry_id}는 source: experimental에 대한 protein_get_structure를 미러링하고, af://{uniprot}는 source: predicted에 대한 그것을 미러링합니다. 많은 MCP 클라이언트는 도구 전용이며 리소스를 표시하지 않습니다; 요약은 도구를 통해 계속 접근할 수 있습니다.

기능

@cyanheads/mcp-ts-core 기반으로 구축:

• 선언적 도구 및 리소스 정의 — 프리미티브당 단일 파일, 프레임워크가 등록 및 검증 처리

• 통합 오류 처리 — 핸들러가 throw하면 프레임워크가 포착, 분류, 포맷

• 플러그형 인증: none, jwt, oauth

• 교체 가능한 스토리지 백엔드: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• 선택적 OpenTelemetry 추적이 포함된 구조화된 로깅

• STDIO 및 Streamable HTTP 전송

단백질 특화:

• 실험(PDB) 및 예측(AlphaFold / 3D-Beacons) 구조에 대한 단일 통합 표면 — 검색, 가져오기, 비교가 두 세계를 동일하게 처리

• 모든 업스트림에서 키 없이 사용 — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro, Foldseek, 프로비저닝할 API 키 없음

• 코퍼스 분석은 RCSB의 패싯 엔진에서 서버 측 실행 — 분포, 히스토그램, 교차 집계를 한 번의 호출로 처리, 행 풀링 및 SQL 워크스페이스 불필요

• 비동기 정렬 및 Foldseek 작업은 제한된 예산 내에서 폴링하고 차단 대신 작업 티켓(ticketId / 쌍별 uuid)을 반환 — ticket_id 또는 resume[] 항목으로 다시 호출하여 동일한 작업을 재제출하지 않고 폴링

에이전트 친화적 출력:

• 모든 응답에 출처 정보 — 각 히트는 source(experimental / predicted), 이를 생성한 엔진 및 데이터베이스, 유효 쿼리 / 총 개수 에코를 포함하여 에이전트가 커버리지를 추론할 수 있음

• 우아한 부분 실패 — 배치 가져오기 및 쌍별 비교는 전체 요청을 실패시키는 대신 항목별 행(failed[], 쌍별 status)을 반환하며, 각각 실행 가능한 복구 텍스트 포함

• 판별된 출력 계약 — 타입화된 source 및 status 유니온, 재개 티켓이 있는 computing 결과, 예산 초과 개요를 통해 호출자가 문자열 파싱이 아닌 데이터로 분기 가능

시작하기

공개 호스팅 인스턴스

공개 인스턴스는 https://protein.caseyjhand.com/mcp에서 사용 가능 — 설치 불필요. Streamable HTTP를 통해 모든 MCP 클라이언트를 연결:

{
  "mcpServers": {
    "protein": {
      "type": "streamable-http",
      "url": "https://protein.caseyjhand.com/mcp"
    }
  }
}

자체 호스팅

MCP 클라이언트 구성 파일에 다음을 추가하세요. API 키가 필요 없습니다 — 모든 업스트림 제공자가 키 없이 사용 가능합니다.

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

또는 npx 사용(Bun 불필요):

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/protein-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

또는 Docker 사용:

{
  "mcpServers": {
    "protein-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/protein-mcp-server:latest"]
    }
  }
}

Streamable HTTP의 경우 전송을 설정하고 서버를 시작하세요:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

사전 요구 사항

• Bun v1.3.2 이상(또는 Node.js v24+).

• 계정 또는 API 키 불필요 — RCSB, AlphaFold DB, 3D-Beacons, UniProt, InterPro, Foldseek는 모두 공개이며 키 없이 사용 가능합니다.

설치

1. 저장소 클론:

git clone https://github.com/cyanheads/protein-mcp-server.git

2. 디렉터리로 이동:

cd protein-mcp-server

3. 의존성 설치:

bun install

구성

모든 업스트림 제공자는 키가 없으므로 서버는 구성 없이 바로 실행됩니다. 아래의 모든 변수는 선택 사항입니다.

제공자 기본 URL 재정의 및 튜닝 제한의 전체 목록은 .env.example를 참조하세요.

서버 실행

로컬 개발

• 빌드 및 실행:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• 검사 및 테스트 실행:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t protein-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 protein-mcp-server

Dockerfile은 기본적으로 HTTP 전송, 무상태 세션 모드로 설정되며 /var/log/protein-mcp-server에 로그를 기록합니다. OpenTelemetry 피어 의존성은 기본적으로 설치됩니다 — 생략하려면 --build-arg OTEL_ENABLED=false로 빌드하세요.

프로젝트 구조

개발 가이드

개발 지침 및 아키텍처 규칙은 CLAUDE.md/AGENTS.md를 참조하세요. 요약:

• 핸들러는 throw하고 프레임워크가 포착 — 도구 로직에 try/catch 없음

• 요청 범위 로깅에는 ctx.log, 테넌트 범위 스토리지에는 ctx.state 사용

• src/mcp-server/*/definitions/index.ts의 배럴을 통해 새 도구 및 리소스 등록

• 외부 API 호출 래핑: 원시 검증 → 도메인 타입으로 정규화 → 출력 스키마 반환; 누락된 필드를 임의로 생성하지 않음

기여

이슈 및 풀 리퀘스트를 환영합니다. 제출 전에 검사 및 테스트를 실행하세요:

bun run devcheck
bun run test

업스트림 데이터 라이선스

구조 및 주석 데이터는 각각 자체 라이선스가 적용되는 공개 업스트림 데이터베이스에서 제공됩니다. protein_get_structure 및 protein_get_annotations는 모든 응답에 attribution 블록을 포함합니다 — 해당 특정 응답에 기여한 각 소스의 라이선스, 인용, 홈페이지 — 따라서 저작자 표시 의무는 여기만이 아니라 다운스트림 소비자에게 데이터와 함께 전달됩니다. CC BY / CC BY-SA 소스는 재배포 시 저작자 표시가 필요합니다. CC0 소스는 인용만 필요합니다(저작자 표시 권장, 필수 아님).

best_available는 3D-Beacons를 통해 예측 모델을 통합하므로 attribution 블록은 실제 기여 제공자(AlphaFold DB, SWISS-MODEL, BFVD, …)를 표시합니다. 큐레이션된 라이선스 항목이 없는 제공자는 3D-Beacons로 연결되는 See provider terms 폴백을 사용하며 임의 생성된 라이선스가 아닙니다. InterPro 자체의 도메인/패밀리 분류는 CC0입니다. 함께 전달되는 GO 용어는 별도로 CC BY 4.0이므로 각각 실제로 기여할 때만 독립적으로 표시됩니다. 각 소스의 전체 인용은 관련 도구 응답의 attribution 블록에 포함됩니다. 이는 업스트림 데이터 라이선스를 다룹니다 — 서버 자체 코드는 별도로 라이선스가 적용됩니다(라이선스 참조).

라이선스

Apache-2.0 — 자세한 내용은 LICENSE를 참조하세요.