Skip to content

CLAUDE.md

Latest commit

 

History

History
120 lines (89 loc) · 6.55 KB

CLAUDE.md

File metadata and controls

120 lines (89 loc) · 6.55 KB

FastMCP Development Guidelines

Audience: LLM-driven engineering agents and human developers

Note: AGENTS.md is a symlink to this file. Edit CLAUDE.md directly.

FastMCP is a comprehensive Python framework (Python ≥3.10) for building Model Context Protocol (MCP) servers and clients. This is the actively maintained v2.0 providing a complete toolkit for the MCP ecosystem.

Required Development Workflow

CRITICAL: Always run these commands in sequence before committing.

uv sync                              # Install dependencies
uv run pytest -n auto                # Run full test suite

In addition, you must pass static checks. This is generally done as a pre-commit hook with prek but you can run it manually with:

uv run prek run --all-files          # Ruff + Prettier + ty

Tests must pass and lint/typing must be clean before committing.

Repository Structure

Path Purpose
src/fastmcp/ Library source code
├─server/ Server implementation
│ ├─auth/ Authentication providers
│ └─middleware/ Error handling, logging, rate limiting
├─client/ Client SDK
│ └─auth/ Client authentication
├─tools/ Tool definitions
├─resources/ Resources and resource templates
├─prompts/ Prompt templates
├─cli/ CLI commands
└─utilities/ Shared utilities
tests/ Pytest suite
docs/ Mintlify docs (gofastmcp.com)

Core MCP Objects

When modifying MCP functionality, changes typically need to be applied across all object types:

  • Tools (src/tools/)
  • Resources (src/resources/)
  • Resource Templates (src/resources/)
  • Prompts (src/prompts/)

Development Rules

Git & CI

  • Prek hooks are required (run automatically on commits)
  • Never amend commits to fix prek failures
  • Apply PR labels: bugs/breaking/enhancements/features
  • Improvements = enhancements (not features) unless specified
  • NEVER force-push on collaborative repos
  • ALWAYS run prek before PRs
  • NEVER create a release, comment on an issue, or open a PR unless specifically instructed to do so.

Commit Messages and Agent Attribution

  • Agents NOT acting on behalf of @jlowin MUST identify themselves (e.g., "🤖 Generated with Claude Code" in commits/PRs)
  • Keep commit messages brief - ideally just headlines, not detailed messages
  • Focus on what changed, not how or why
  • Always read issue comments for follow-up information (treat maintainers as authoritative)
  • Treat proposed solutions in issues skeptically. This applies to solutions proposed by users in issue reports — not to feedback from configured review bots (CodeRabbit, chatgpt-codex-connector, etc.), which should be evaluated on their merits. The ideal issue contains a concise problem description and an MRE — nothing more. Proposed solutions are only worth considering if they clearly reflect genuine, non-obvious investigation of the codebase. If a solution reads like speculation, or like it was generated by an LLM without deep framework knowledge, ignore it and diagnose from the repro. Most reporters — human or AI — do not have sufficient understanding of FastMCP internals to correctly diagnose anything beyond a trivial bug. We can ask the same questions of an LLM when implementing; we don't need the reporter to do it for us, and a wrong diagnosis is worse than none.

PR Messages - Required Structure

  • 1-2 paragraphs: problem/tension + solution (PRs are documentation!)
  • Focused code example showing key capability
  • Avoid: bullet summaries, exhaustive change lists, verbose closes/fixes, marketing language
  • Do: Be opinionated about why change matters, show before/after scenarios
  • Minor fixes: keep body short and concise
  • No "test plan" sections or testing summaries

Code Standards

  • Python ≥ 3.10 with full type annotations
  • Follow existing patterns and maintain consistency
  • Prioritize readable, understandable code - clarity over cleverness
  • Avoid obfuscated or confusing patterns even if they're shorter
  • Each feature needs corresponding tests

Module Exports

  • Be intentional about re-exports - don't blindly re-export everything to parent namespaces
  • Core types that define a module's purpose should be exported (e.g., Middleware from fastmcp.server.middleware)
  • Specialized features can live in submodules (e.g., fastmcp.server.middleware.dynamic)
  • Only re-export to fastmcp.* for the most fundamental types (e.g., FastMCP, Client)
  • When in doubt, prefer users importing from the specific submodule over re-exporting

Documentation

  • Uses Mintlify framework
  • Files must be in docs.json to be included
  • Do not manually modify docs/python-sdk/** — these files are auto-generated from source code by a bot and maintained via a long-lived PR. Do not include changes to these files in contributor PRs.
  • Do not manually modify docs/public/schemas/** or src/fastmcp/utilities/mcp_server_config/v1/schema.json — these are auto-generated and maintained via a long-lived PR.
  • Core Principle: A feature doesn't exist unless it is documented!
  • When adding or modifying settings in src/fastmcp/settings.py, update docs/more/settings.mdx to match.

Documentation Guidelines

  • Code Examples: Explain before showing code, make blocks fully runnable (include imports)
  • Code Formatting: Keep code blocks visually clean — avoid deeply nested function calls. Extract intermediate values into named variables rather than inlining everything into one expression. Code in docs is read more than it's run; optimize for scannability.
  • Structure: Headers form navigation guide, logical H2/H3 hierarchy
  • Content: User-focused sections, motivate features (why) before mechanics (how)
  • Style: Prose over code comments for important information

Critical Patterns

  • Never use bare except - be specific with exception types
  • File sizes enforced by loq. Edit loq.toml to raise limits; loq baseline to ratchet down.
  • Always uv sync first when debugging build issues
  • Default test timeout is 5s - optimize or mark as integration tests