mcp-python-sdk/CLAUDE.md

Tool Usage Learnings

This file is intended to be used by an LLM such as Claude.

UV Package Manager

• Use uv run to run Python tools without activating virtual environments
• For formatting: uv run ruff format .
• For type checking: uv run pyright
• For upgrading packages:
  • uv add --dev package --upgrade-package package to upgrade a specific package
  • Don't use @latest syntax - it doesn't work
  • Be careful with uv pip install as it may downgrade packages

Git and GitHub CLI

• When using gh CLI for PRs, always quote title and body:

  gh pr create --title "\"my title\"" --body "\"my body\""
  

• For git commits, use double quotes and escape inner quotes:

  git commit -am "\"fix: my commit message\""
  

Python Tools

Ruff

• Handles both formatting and linting
• For formatting: uv run ruff format .
• For checking: uv run ruff check .
• For auto-fixing: uv run ruff check . --fix
• Common issues:
  • Line length (default 88 chars)
  • Import sorting (I001 errors)
  • Unused imports
• When line length errors occur:
  • For strings, use parentheses and line continuation
  • For function calls, use multiple lines with proper indentation
  • For imports, split into multiple lines

Pyright

• Type checker
• Run with: uv run pyright
• Version warnings can be ignored if type checking passes
• Common issues:
  • Optional types need explicit None checks
  • String operations need type narrowing

Pre-commit Hooks

• Configuration in .pre-commit-config.yaml
• Runs automatically on git commit
• Includes:
  • Prettier for YAML/JSON formatting
  • Ruff for Python formatting and linting
• When updating ruff version:
  • Check available versions on PyPI
  • Update rev in config to match available version
  • Add and commit config changes before other changes

Best Practices

1. Always check git status and diff before committing
2. Run formatters before type checkers
3. When fixing CI:
   • Start with formatting issues
   • Then fix type errors
   • Then address any remaining linting issues
4. For type errors:
   • Get full context around error lines
   • Consider optional types
   • Add type narrowing checks when needed