SHAP MCP Server (shap-mcp)

SHAP(SHapley Additive exPlanations) 모델 설명 가능성을 에이전트 호출 가능한 도구로 노출하는 가볍고 집중된 Model Context Protocol (MCP) 서버입니다.

AI 어시스턴트(예: Claude Desktop)와 인간 데이터 과학자가 공유 인메모리 세션에서 원활하게 협업할 수 있도록 설계되었습니다.

주요 기능

• 이중 동시 전송: Claude Desktop용 표준 stdio 전송과 함께 웹 GUI 및 생성된 시각화를 제공하는 포트 8765의 Starlette HTTP 전송.

• 통합 인메모리 세션: 웹 GUI에서 분석을 실행하고 Claude에서 질문하거나, Claude가 분석을 트리거하고 생성된 플롯을 GUI 갤러리에서 즉시 확인.

• 범용 모델 지원:

  • tree: XGBoost, LightGBM, CatBoost, RandomForest, ExtraTrees에 대한 정확한 TreeExplainer.

  • linear: 로지스틱 회귀, Ridge, Lasso에 대한 빠른 폐쇄형 LinearExplainer.

  • deep: PyTorch 신경망용 DeepExplainer.

  • kernel: 자동 kmeans 클러스터링을 사용한 모델 불가지론적 KernelExplainer.

• 출판 준비 완료 시각화: 사전 형식화된 클릭 가능한 브라우저 및 로컬 파일 링크와 함께 6가지 플롯 유형(summary, bar, waterfall, force, dependence, heatmap)을 생성하고 저장.

• URL 및 파일 수집: 로컬 경로 또는 공개 HTTP/HTTPS URL에서 모델 및 CSV 데이터세트를 스트리밍 다운로드, 자동 크기 제한(SHAP_MCP_MAX_DOWNLOAD_MB), 임시 파일 정리와 함께 수집.

• 보안: HTTP 엔드포인트에 대한 선택적 API 키 인증(SHAP_MCP_API_KEY).

Related MCP server: my-mcp-server2

설치

# Standard installation
pip install shap-mcp

# Optional extra for PyTorch DeepExplainer support
pip install shap-mcp[deep]

Claude Desktop 구성

claude_desktop_config.json에 shap-mcp를 추가하세요:

범용 권장 설정 (uvx 사용)

{
  "mcpServers": {
    "shap-mcp": {
      "command": "uvx",
      "args": ["shap-mcp", "--no-ui"]
    }
  }
}

직접 Pip / Pipx 설정

{
  "mcpServers": {
    "shap-mcp": {
      "command": "shap-mcp",
      "args": ["--no-ui"]
    }
  }
}

도구 참조

런타임 구성

모든 런타임 구성은 환경 변수를 통해 관리됩니다:

웹 GUI

shap-mcp로 직접 시작하면 서버가 http://localhost:8765/ui/에서 웹 GUI를 자동으로 엽니다:

• 구성 양식: 로컬 경로 또는 URL 입력, 모델 아키텍처 선택, 분석 실행.

• 실시간 배지: 로드된 모델 상태, 분석된 행 수, 활성 설명자 유형을 실시간 표시.

• 동적 플롯 갤러리: Claude 또는 GUI가 시각화를 생성하면 썸네일이 자동으로 나타납니다.

• 인스턴스 설명자: 개별 특징 기여도의 대화형 테이블.

예정 기능 및 로드맵

다음 기능이 향후 릴리스에서 계획되어 있습니다:

• save_analysis / load_analysis: 계산된 SHAP 값을 .npz 파일로 직렬화하여 재로드 시 재계산을 건너뛰고 팀 간 결과 공유.

• 인증 보호 원격 수집: Hugging Face 토큰, 프라이빗 S3/GCS 버킷, 사전 서명된 URL 지원.

• 탭 GUI 및 점진적 공개: 웹 GUI를 깔끔하고 집중된 탭으로 재설계하고 분석 완료에 따라 점진적으로 잠금 해제.

• 대화형 시각화: mpld3를 통한 matplotlib 차트의 팬, 줌, 툴팁 호버 지원.

• 플롯별 안내 프롬프트: 6가지 시각화 유형 각각에 맞춘 전용 MCP 프롬프트.

• 멀티 테넌트 세션 격리: 공유 다중 사용자 서버 배포를 위한 연결 격리 세션 상태.

• 추가 모델 형식: ONNX 런타임, MLflow 모델, Weights & Biases 모델 레지스트리 기본 지원.

• 공정성 및 편향 분해: 하위 그룹별 인구통계적 패리티 및 슬라이스 기반 SHAP 분석.

• MCP-UI 인라인 캔버스 및 로컬 드래그 앤 드롭: MCP-UI / MCP Apps 사양을 통한 채팅 내 캔버스 렌더링 및 로컬 드래그 앤 드롭 파일 수집으로 외부 브라우저 탭 및 클라우드 첨부 마찰 제거.

라이선스

MIT 라이선스. 자세한 내용은 LICENSE를 참조하세요.