mcp-python-sdk/CLAUDE.md

Development Guidelines

This document contains critical information about working with this codebase. Follow these guidelines precisely.

Core Development Rules

1. Package Management

   • ONLY use uv, NEVER pip
   • Installation: uv add package
   • Running tools: uv run tool
   • Upgrading: uv add --dev package --upgrade-package package
   • FORBIDDEN: uv pip install, @latest syntax

2. Code Quality

   • Type hints required for all code
   • Public APIs must have docstrings
   • Functions must be focused and small
   • Follow existing patterns exactly
   • Line length: 88 chars maximum

3. Testing Requirements

   • Framework: uv run pytest
   • Async testing: use anyio, not asyncio
   • Coverage: test edge cases and errors
   • New features require tests
   • Bug fixes require regression tests

4. Version Control

   • Commit messages: conventional format (fix:, feat:)
   • PR scope: minimal, focused changes
   • PR requirements: description, test plan
   • Always include issue numbers
   • Quote handling:

     git commit -am "\"fix: message\""
     gh pr create --title "\"title\"" --body "\"body\""
     

Code Formatting

1. Ruff

   • Format: uv run ruff format .
   • Check: uv run ruff check .
   • Fix: uv run ruff check . --fix
   • Critical issues:
     • Line length (88 chars)
     • Import sorting (I001)
     • Unused imports
   • Line wrapping:
     • Strings: use parentheses
     • Function calls: multi-line with proper indent
     • Imports: split into multiple lines

2. Type Checking

   • Tool: uv run pyright
   • Requirements:
     • Explicit None checks for Optional
     • Type narrowing for strings
     • Version warnings can be ignored if checks pass

3. Pre-commit

   • Config: .pre-commit-config.yaml
   • Runs: on git commit
   • Tools: Prettier (YAML/JSON), Ruff (Python)
   • Ruff updates:
     • Check PyPI versions
     • Update config rev
     • Commit config first

Error Resolution

1. CI Failures

   • Fix order:
     1. Formatting
     2. Type errors
     3. Linting
   • Type errors:
     • Get full line context
     • Check Optional types
     • Add type narrowing
     • Verify function signatures

2. Common Issues

   • Line length:
     • Break strings with parentheses
     • Multi-line function calls
     • Split imports
   • Types:
     • Add None checks
     • Narrow string types
     • Match existing patterns

3. Best Practices

   • Check git status before commits
   • Run formatters before type checks
   • Keep changes minimal
   • Follow existing patterns
   • Document public APIs
   • Test thoroughly