biopython-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 Model Context Protocol (MCP) server that exposes BioPython library capabilities as tools for AI assistants. It allows AI models to perform bioinformatics operations like sequence analysis, alignment, database access, structural analysis, and phylogenetics.

Development Commands

Setup

pip install -e ".[dev]"

Running the Server

biopython-mcp
# Or directly:
python -m biopython_mcp.server

Testing

# Run all tests with coverage
pytest

# Run specific test file
pytest tests/test_sequence.py

# Run specific test class or function
pytest tests/test_sequence.py::TestTranslateSequence
pytest tests/test_sequence.py::TestTranslateSequence::test_translate_simple_dna

Code Quality

# Format code (REQUIRED before commit)
black biopython_mcp/ tests/

# Lint code
ruff check biopython_mcp/ tests/

# Type checking
mypy biopython_mcp/

IMPORTANT: Always run black before committing to ensure code passes CI lint checks. Quick pre-commit check:

black biopython_mcp/ tests/ && ruff check biopython_mcp/ tests/

Architecture

Tool Registration Pattern

The server uses FastMCP to expose BioPython functions as MCP tools. All tool functions follow this pattern:

1. Tool modules (src/sequence.py, src/alignment.py, etc.) contain individual tool functions
2. Each tool function returns a dictionary with {"success": bool, ...} format
3. Central registration in src/server.py imports and registers all tools with mcp.tool()

To add a new tool:

1. Create the function in the appropriate module (or create a new module)
2. Ensure it returns a dict with success field
3. Import and register it in src/server.py using mcp.tool()(your_function)

Error Handling Convention

All tool functions use try-except blocks and return error information in the response dict: