cbioportal-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a cBioPortal MCP (Model Context Protocol) server that provides AI assistants with access to cancer genomics data from cBioPortal. The server is built using FastMCP and implements full asynchronous support for high-performance data retrieval.

Key Architecture

Core Components

• cbioportal_mcp/server.py - Main MCP server implementation using FastMCP framework
• cbioportal_mcp/api_client.py - Dedicated HTTP client class for cBioPortal API requests
• cbioportal_mcp/endpoints/ - Domain-specific endpoint modules:
  • base.py - BaseEndpoint pattern with shared pagination, validation, and error handling
  • studies.py - Cancer studies endpoints
  • genes.py - Gene operations and mutations
  • samples.py - Sample data management
  • molecular_profiles.py - Molecular and clinical data
• cbioportal_mcp/utils/ - Shared utilities for pagination, validation, and logging
• cbioportal_mcp/config.py - Multi-layer configuration system (CLI > ENV > YAML > defaults)
• tests/ - Comprehensive test suite with 93 passing tests

Architectural Patterns

• BaseEndpoint Pattern: All endpoint classes inherit from BaseEndpoint, which provides:
  • Automatic API client initialization via _ensure_api_client_ready()
  • Shared pagination logic with paginated_request()
  • Consistent error handling via @handle_api_errors decorator
  • Parameter validation via @validate_paginated_params decorator
• Dependency Injection: Configuration and APIClient are injected into endpoints
• Async-First Design: All API operations are fully asynchronous
• Modular Structure: Clear separation of concerns with domain-specific modules

Development Commands

Environment Setup

# Install/sync dependencies (using uv package manager)
uv sync

# Install in editable mode (required for Claude Desktop integration)
uv pip install -e .

# Add new dependencies
uv add package-name

# Add development dependencies
uv add --dev package-name