Mutation Clinical Trial Matching MCP

돌연변이 임상시험 매칭 MCP

Claude Desktop이 돌연변이를 기반으로 clincialtrials.gov에서 일치 항목을 검색할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.

상태

현재 개발의 첫 단계입니다. 클로드 쿼리에서 주어진 돌연변이를 기반으로 시행을 검색하는 방식으로 작동합니다. 하지만 아직 버그가 있고, 추가적인 개선 및 추가 기능이 구현되어야 합니다.

개요

이 프로젝트는 Agentic Coding 원칙을 따라 Claude Desktop과 clinicaltrials.gov API를 통합하는 시스템을 구축합니다. 이 서버는 유전자 돌연변이에 대한 자연어 질의를 허용하고 관련 임상 시험에 대한 요약 정보를 제공합니다.

지엑스피1

흐름의 각 노드는 prep , exec 및 post 메서드가 있는 PocketFlow 노드 패턴을 따릅니다.

프로젝트 구조

이 프로젝트는 Agentic Coding 패러다임에 따라 구성됩니다.

1. 요구 사항 (인간 주도):
   • 특정 유전자 돌연변이와 관련된 임상 시험을 검색하고 요약합니다.
   • 문맥적 리소스로 돌연변이 정보 제공
   • Claude Desktop과 완벽하게 통합
2. 흐름 설계 (협업):
   • 사용자가 Claude Desktop에 유전자 돌연변이에 대해 질문합니다.
   • Claude는 우리의 MCP 서버 도구를 호출합니다.
   • 서버 쿼리 clinicaltrials.gov API
   • 서버는 결과를 처리하고 요약합니다.
   • 서버는 Claude에게 포맷된 결과를 반환합니다.
3. 유틸리티 (협업):
   • clinicaltrials/query.py : clinicaltrials.gov에 대한 API 호출을 처리합니다.
   • utils/call_llm.py : Claude 작업을 위한 유틸리티
4. 노드 디자인 (AI 주도):
   • utils/node.py : prep/exec/post 패턴을 사용하여 기본 Node 및 BatchNode 클래스를 구현합니다.
   • clinicaltrials/nodes.py : 쿼리 및 요약을 위한 특수 노드를 정의합니다.
   • clinicaltrials_mcp_server.py : 흐름 실행을 조율합니다.
5. 구현 (AI 주도):
   • 프로토콜 세부 정보를 처리하기 위한 FastMCP SDK
   • 모든 레벨에서 오류 처리
   • 일반적인 돌연변이에 대한 리소스

구성 요소

MCP 서버( clinicaltrials_mcp_server.py )

공식 Python SDK를 사용하여 모델 컨텍스트 프로토콜 인터페이스를 구현하는 주요 서버입니다.

• Claude가 사용할 수 있는 도구를 등록하고 공개합니다.
• 일반적인 돌연변이에 대한 정보를 제공하는 리소스입니다.
• Claude Desktop과의 통신을 처리합니다.

쿼리 모듈( clinicaltrials/query.py )

clinicaltrials.gov API에 대한 쿼리를 담당합니다.

• 강력한 오류 처리
• 입력 검증
• 자세한 로깅

요약기( llm/summarize.py )

임상 시험 데이터를 처리하고 포맷합니다.

• 단계별로 시험을 구성합니다
• 주요 정보(NCT ID, 요약, 조건 등)를 추출합니다.
• 읽기 쉬운 마크다운 요약을 만듭니다.

노드 패턴 구현

이 프로젝트는 AI 워크플로우를 구축하는 데 있어 모듈식이고 유지 관리가 가능한 접근 방식을 제공하는 PocketFlow Node 패턴을 구현합니다.

핵심 노드 클래스( utils/node.py )

• 노드 : 데이터 처리를 위한 prep , exec , post 메서드를 갖춘 기본 클래스
• BatchNode : 여러 항목을 일괄 처리하기 위한 확장
• Flow : 노드의 실행을 순서대로 조정합니다.

구현 노드( clinicaltrials/nodes.py )

1. QueryTrialsNode :
   # Queries clinicaltrials.gov API def prep(self, shared): return shared["mutation"] def exec(self, mutation): return query_clinical_trials(mutation) def post(self, shared, mutation, result): shared["trials_data"] = result shared["studies"] = result.get("studies", []) return "summarize"
2. SummarizeTrialsNode :
   # Formats trial data into readable summaries def prep(self, shared): return shared["studies"] def exec(self, studies): return format_trial_summary(studies) def post(self, shared, studies, summary): shared["summary"] = summary return None # End of flow

흐름 실행

MCP 서버는 흐름을 생성하고 실행합니다.

이 패턴은 준비, 실행, 사후 처리를 분리하여 코드의 유지 관리 및 테스트 용이성을 높입니다. 자세한 내용은 디자인 문서를 참조하세요.

용법

1. uv를 사용하여 종속성을 설치합니다.
   uv pip install -r requirements.txt
2. Claude Desktop 구성:
   • ~/Library/Application Support/Claude/claude_desktop_config.json 의 구성은 이미 설정되어 있어야 합니다.
3. Claude Desktop을 시작하고 다음과 같은 질문을 해보세요.
   • "EGFR L858R 돌연변이에 대한 임상 시험은 어떤 것이 있나요?"
   • "BRAF V600E 돌연변이에 대한 임상 시험이 있나요?"
   • "ALK 재배열에 대한 시험에 대해 알려주세요"
4. 다음과 같이 질문하여 리소스를 활용하세요.
   • "KRAS G12C 돌연변이에 대해 더 자세히 말씀해 주실 수 있나요?"

Claude Desktop과 통합

이 프로젝트를 Claude Desktop MCP 도구로 구성할 수 있습니다. 구성에서 경로 자리 표시자를 사용하고 실제 경로로 대체하세요.

경로 변수:

• {PATH_TO_VENV} : 가상 환경 디렉토리의 전체 경로입니다.
• {PATH_TO_PROJECT} : 프로젝트 파일이 있는 디렉토리의 전체 경로입니다.

설치 지침:

1. 저장소를 로컬 컴퓨터에 복제합니다.
2. 아직 uv가 없다면 설치하세요:
   curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux # or iwr -useb https://astral.sh/uv/install.ps1 | iex # Windows PowerShell
3. 가상 환경을 만들고 한 단계로 종속성을 설치하세요.
   uv venv .venv uv pip install -r requirements.txt
4. 필요할 때 가상 환경을 활성화하세요.
   source .venv/bin/activate # macOS/Linux .venv\Scripts\activate # Windows
5. 가상 환경과 프로젝트 디렉토리의 전체 경로를 확인하세요.
6. 이러한 특정 경로로 구성을 업데이트하세요.

예:

• macOS/Linux의 경우:
  "command": "/Users/username/projects/mutation_trial_matcher/.venv/bin/python"
• Windows의 경우:
  "command": "C:\\Users\\username\\projects\\mutation_trial_matcher\\.venv\\Scripts\\python.exe"

길 찾기 팁:

• 가상 환경에서 Python 인터프리터의 정확한 경로를 찾으려면 다음을 실행하세요.
  • which python (macOS/Linux)
  • where python (Windows, venv 활성화 후)
• 프로젝트 경로의 경우 clinicaltrials_mcp_server.py 포함된 디렉토리의 전체 경로를 사용하세요.

향후 개선 사항

계획된 개선 사항과 향후 작업에 대한 포괄적인 목록은 future_work.md 문서를 참조하세요.

종속성

이 프로젝트는 다음과 같은 주요 종속성에 의존합니다.

• Python 3.7+ - 기본 런타임 환경
• PocketFlow ( pocketflow>=0.0.1 ) - Node 패턴을 사용하여 모듈형 AI 워크플로를 구축하기 위한 프레임워크
• MCP SDK ( mcp[cli]>=1.0.0 ) - Claude Desktop 도구를 빌드하기 위한 공식 모델 컨텍스트 프로토콜 SDK
• 요청 ( requests==2.31.0 ) - clinicaltrials.gov에 대한 API 호출을 위한 HTTP 라이브러리
• Python-dotenv ( python-dotenv==1.1.0 ) - .env 파일에서 환경 변수를 로드하기 위해

모든 종속성은 설치 지침에 설명된 대로 uv를 사용하여 설치할 수 있습니다.

문제 해결

Claude Desktop이 MCP 서버에서 연결을 끊는 경우:

• ~/Library/Logs/Claude/mcp-server-clinicaltrials-mcp.log 에서 로그를 확인하세요.
• Claude Desktop을 다시 시작하세요
• 서버가 올바르게 실행되고 있는지 확인하세요

개발 프로세스

이 프로젝트는 인간이 설계하고 AI 에이전트가 구현하는 에이전트 코딩(Agentic Coding) 원칙을 따르는 AI 지원 코딩 방식을 사용하여 개발되었습니다. 메인 프로그램의 원본은 2025년 4월 30일에 구축되었습니다. 구현은 다음과 같은 페어 프로그래밍을 통해 이루어졌습니다.

• 윈드서핑
  • 채팅GPT 4.1
  • 클로드 3.7 소네트

이러한 AI 보조 기능은 높은 수준의 설계 요구 사항을 기능적 코드로 변환하고, API 통합을 돕고, 모범 사례에 따라 프로젝트를 구성하는 데 중요한 역할을 했습니다.

.windsurfrules 문자 제한 처리

템플릿 저장소의 PocketFlow .windsurfrules 파일에는 포괄적인 프로젝트 규칙이 포함되어 있지만, Windsurf는 규칙 파일의 글자 수를 6,000자로 제한합니다. 즉, 전체 가이드라인을 프로젝트에 직접 포함할 수 없으며, 중요한 규칙이 생략되거나 잘릴 수 있습니다.

이 문제를 해결하기 위해 권장되는 솔루션은 두 가지입니다.

1. Windsurf 🪁 메모리를 사용하여 규칙 저장

Windsurf의 메모리 기능을 활용하면 .windsurfrules 파일 제한을 초과하더라도 PocketFlow 규칙 전체 세트를 저장할 수 있습니다. 이 방법을 사용하면 Windsurf와 함께 사용할 때 모든 프로젝트 규칙과 모범 사례를 참조할 수 있으므로 잘림으로 인해 손실되는 내용이 없습니다. 단계별 지침과 메모리 파일과 규칙 파일의 자세한 비교는 docs/memory_vs_windsurfrules.md 를 참조하세요.

2. Context7을 사용하여 가이드라인에 액세스하기

중요 참고 사항 : 이 프로젝트는 포괄적인 .windsurfrules 파일이 포함된 PocketFlow-Template-Python 저장소를 기반으로 합니다. 그러나 Windsurf의 규칙 파일 크기는 6,000자로 제한되어 있으므로 PocketFlow 가이드라인 전체를 Windsurf 메모리에 로드할 수 없습니다.

이러한 한계를 해결하기 위해 개발 과정에서 Context7 MCP 서버를 사용하여 PocketFlow 가이드라인에 접근하는 방법에 대한 자세한 지침을 마련했습니다. 이 방법을 사용하면 문자 수 제한 없이 PocketFlow의 디자인 패턴과 모범 사례를 최대한 활용할 수 있습니다.

PocketFlow와 함께 Context7을 사용하는 방법에 대한 자세한 내용은 Context7 가이드 를 참조하세요. 이 가이드에는 다음 내용이 포함되어 있습니다.

• Windsurf에서 Context7 MCP를 구성하기 위한 단계별 지침
• PocketFlow 문서에 접근하기 위한 자연어 프롬프트
• 특정 구현 패턴을 검색하는 예
• 중요한 패턴을 나중에 참고할 수 있도록 추억으로 저장하는 방법

이 가이드를 따르면 이 프로젝트를 개발하고 확장하는 동안 PocketFlow의 Agentic Coding 원칙을 준수할 수 있습니다.

감사의 말

이 프로젝트는 PocketFlow-Template-Python을 기반으로 구축되었습니다. 이 구현을 가능하게 한 기반과 구조를 제공해 주신 해당 프로젝트의 초기 기여자분들께 특별히 감사드립니다.

이 프로젝트는 원래 템플릿에 설명된 Agentic Coding 방법론을 따릅니다.

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.