# Repository: PrefectHQ/fastmcp # Stars: 24611 ## CLAUDE.md # 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. ```bash 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: ```bash 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/`) **Before writing cross-component logic (dedupe, grouping, lookups, identity checks), read `FastMCPComponent` in `src/fastmcp/utilities/components.py`.** The base class defines the shared surface — `name`, `version`, `tags`, `meta`, and critically the `key` property which is the canonical MCP identity (encodes type, identifier, and version). Prefer `item.key` over ad-hoc `name or uri or uri_template` fallbacks; overrides in `Resource` and `ResourceTemplate` already handle URI-based identity, and `.key` includes the version suffix so variants of the same component don't falsely collide. ## Development Rules **Read `CONTRIBUTING.md` before opening issues or PRs.** It describes when PRs are appropriate, what we expect from enhancement proposals, and what we'll close without review. ### 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. - **NEVER** merge a PR marked as do-not-merge or draft. Check title, body, AND labels for `[DNM]`, `DNM`, `DO NOT MERGE`, `DON'T MERGE`, `DONT MERGE`, `do-not-merge`, `dont-merge`, `[DRAFT]`, or `DRAFT` (case-insensitive, any variation — some authors use `[DRAFT]` in the title even when `isDraft` is false). Authors use these as hard stops — respect them even if CI is green and review looks clean. When triaging a batch of PRs, filter these out up front AND re-check each one's labels immediately before merging, since labels can change mid-session. - **ALWAYS** read review-bot comments before approving a PR. CodeRabbit and chatgpt-codex-connector (Codex) leave substantive review comments on most PRs in this repo — these bots have read the diff and often flag real issues that aren't in the PR description. Use `gh pr view --comments` and read the bot feedback as part of review. Unlike proposed solutions from issue reporters, review-bot feedback should be evaluated on its merits, not discounted. ### Releases Only cut releases when the maintainer explicitly asks. Tags follow `v` (e.g., `v3.2.0`). Always pass `--generate-notes` so the auto-generated changelog appears at the bottom. **The title pun is critical.** Titles follow `v: ` where the pun relates to the most important theme of the release. Propose multiple options and let the maintainer choose — never pick one yourself. Look at recent releases for tone (e.g., "Code to Joy" for the code mode release, "Three at Last" for 3.0). Write the maintainer-approved handwritten notes to a temporary file, then create the release. `--generate-notes` appends the auto-generated changelog after the handwritten content. ```bash gh release create v3.2.0 --target main --title "v3.2.0: Theme Here" --generate-notes --notes-file /tmp/release-notes.md ``` Most releases target `main`, but maintenance or backport releases may target a different branch (e.g., `release/2.x`). Confirm the target with the maintainer if there's any ambiguity. The handwritten notes are prepended above the auto-generated changelog and are the part that matters. Do not include a title in the notes body — the release title (`v{version}: {pun}`) already serves as the heading. Work with the maintainer to draft the notes — propose a draft, get feedback, iterate. Do not publish without the maintainer's sign-off. **Before drafting, always read recent existing releases** (`gh release list` then `gh release view `) to absorb the voice, structure, and level of detail. Each release builds on the tone of previous ones — don't guess at the style from these instructions alone. **To preview what PRs will be in the release** before it's cut, call the GitHub generate-notes API. This returns the exact auto-generated changelog that `--generate-notes` would append, so you can see the full PR list — useful for picking a pun theme and making sure nothing's been missed: ```bash gh api -X POST repos/PrefectHQ/fastmcp/releases/generate-notes \ -f tag_name=v3.2.3 \ -f target_commitish=main \ -f previous_tag_name=v3.2.2 \ --jq '.body' ``` **Point releases** (3.0, 3.1, 3.2) get narrative prose: open with the theme of the release, then walk through headline features conceptually — what they enable, why they matter, how they fit together. Write it the way a blog post reads, not a changelog. Multiple paragraphs, code examples where they clarify. **Patch releases** (3.1.1, 3.0.2) get 1-2 sentences explaining what broke and what the fix does. Keep it minimal — the auto-generated changelog has the details. ### 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 Review Guidelines - **Fix causes, not symptoms.** When a PR works around a problem instead of addressing why it occurs, that's a red flag. A side-channel that compensates for a missing step adds permanent complexity. If the fix doesn't change the code path where the bug actually happens, ask why not. - Focus on API design and naming clarity - Identify confusing patterns (e.g., parameter values that contradict defaults) or non-idiomatic code (mutable defaults, etc.). Contributed code will need to be maintained indefinitely, and by someone other than the author (unless the author is a maintainer). - Suggest specific improvements, not generic "add more tests" comments - Think about API ergonomics from a user perspective ### 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 - **Docstrings:** FastMCP docstrings are automatically compiled into MDX documents. Use markdown (single backticks, fenced code blocks), not RST (no double backticks). Bare `{}` in examples will be interpreted as JSX — wrap in backticks instead. ## Critical Patterns - Never use bare `except` - be specific with exception types - File sizes enforced by [loq](https://github.com/jakekaplan/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 ## README.md
FastMCP Logo # FastMCP 🚀 Move fast and make things. *Made with 💙 by [Prefect](https://www.prefect.io/)* [![Docs](https://img.shields.io/badge/docs-gofastmcp.com-blue)](https://gofastmcp.com) [![Discord](https://img.shields.io/badge/community-discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/uu8dJCgttd) [![PyPI - Version](https://img.shields.io/pypi/v/fastmcp.svg)](https://pypi.org/project/fastmcp) [![Tests](https://github.com/PrefectHQ/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/PrefectHQ/fastmcp/actions/workflows/run-tests.yml) [![License](https://img.shields.io/github/license/PrefectHQ/fastmcp.svg)](https://github.com/PrefectHQ/fastmcp/blob/main/LICENSE) prefecthq%2Ffastmcp | Trendshift
--- The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) connects LLMs to tools and data. FastMCP gives you everything you need to go from prototype to production: ```python from fastmcp import FastMCP mcp = FastMCP("Demo 🚀") @mcp.tool def add(a: int, b: int) -> int: """Add two numbers""" return a + b if __name__ == "__main__": mcp.run() ``` ## Why FastMCP Building an effective MCP application is harder than it looks. FastMCP handles all of it. Declare a tool with a Python function, and the schema, validation, and documentation are generated automatically. Connect to a server with a URL, and transport negotiation, authentication, and protocol lifecycle are managed for you. You focus on your logic, and the MCP part just works: **with FastMCP, best practices are built in.** **That's why FastMCP is the standard framework for working with MCP.** FastMCP 1.0 was incorporated into the official MCP Python SDK in 2024. Today, the actively maintained standalone project is downloaded a million times a day, and some version of FastMCP powers 70% of MCP servers across all languages. FastMCP has three pillars:
Servers
Servers
Expose tools, resources, and prompts to LLMs. 		Apps
Apps
Give your tools interactive UIs rendered directly in the conversation. 		Clients
Clients
Connect to any MCP server — local or remote, programmatic or CLI.
**[Servers](https://gofastmcp.com/servers/server)** wrap your Python functions into MCP-compliant tools, resources, and prompts. **[Clients](https://gofastmcp.com/clients/client)** connect to any server with full protocol support. And **[Apps](https://gofastmcp.com/apps/overview)** give your tools interactive UIs rendered directly in the conversation. Ready to build? Start with the [installation guide](https://gofastmcp.com/getting-started/installation) or jump straight to the [quickstart](https://gofastmcp.com/getting-started/quickstart). When you're ready to deploy, [Prefect Horizon](https://www.prefect.io/horizon) offers free hosting for FastMCP users. ## Installation We recommend installing FastMCP with [uv](https://docs.astral.sh/uv/): ```bash uv pip install fastmcp ``` For full installation instructions, including verification and upgrading, see the [**Installation Guide**](https://gofastmcp.com/getting-started/installation). **Upgrading?** We have guides for: - [Upgrading from FastMCP v2](https://gofastmcp.com/getting-started/upgrading/from-fastmcp-2) - [Upgrading from the MCP Python SDK](https://gofastmcp.com/getting-started/upgrading/from-mcp-sdk) - [Upgrading from the low-level SDK](https://gofastmcp.com/getting-started/upgrading/from-low-level-sdk) ## 📚 Documentation FastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns. Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily: - [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation. - [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM. **Community:** Join our [Discord server](https://discord.gg/uu8dJCgttd) to connect with other FastMCP developers and share what you're building. ## Contributing We welcome contributions! See the [Contributing Guide](https://gofastmcp.com/development/contributing) for setup instructions, testing requirements, and PR guidelines.