AGENTS.md · PrefectHQ/fastmcp

Sections

1. Required Development Workflow
2. Repository Structure
3. Skills
4. Core MCP Objects
5. Development Rules
6. Code Review Rules
7. Critical Patterns

First lines (shown under the repo's Apache-2.0 license)

# FastMCP Development Guidelines

> **Audience**: LLM-driven engineering agents and human developers

FastMCP is a comprehensive Python framework (Python ≥3.10) for building Model Context Protocol (MCP) servers and clients.

## Required Development Workflow

Install dependencies before running local checks:

```bash
uv sync                              # Install dependencies
```

Run the tests relevant to the behavior you changed, including neighboring paths
that share the implementation. For example:

```bash
uv run pytest tests/skills tests/utilities/test_skills.py -n 0
```

Broaden the selection when a concrete dependency or failure warrants it and the
check is expedient. Full-suite and platform-matrix testing belong in CI; do not
run the full suite locally by default or repeat it for each commit or PR in a
stack. Run it locally only when explicitly requested or when investigating a
failure that requires it.

In addition, you must pass static checks. These generally run as pre-commit hooks
with `prek`. To check changed files before committing:

```bash
uv run prek run --files path/to/changed_file.py
```

For repository-wide configuration changes, run:

```bash
uv run prek run --all-files          # Ruff + Prettier + ty + gitleaks
```

The gitleaks hook needs the `gitleaks` binary on `PATH` (`brew install gitleaks`, or see [gitleaks releases](https://github.com/gitleaks/gitleaks/releases)) — it isn't a `uv`-managed dependency, so `uv sync` alone won't provide it.

**Relevant tests and applicable static checks must pass before committing.**

## Repository Structure

| Path              | Purpose                                |
| ----------------- | -------------------------------------- |
| `fastmcp_slim/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)          |

## Skills

Repository skills live in `.agents/skills/`. [The development guide](docs/development/contributing.mdx#maintenance-and-automation) says which work is automated and which needs a person. Load the skill that matches the job:

| Job | Skill |
| --- | --- |
| Find worthwhile issues in a backlog or release window | `triage` |
| Decide whether to assign an external contributor | `review-issue` |
| Fix a chosen bug through to a PR | `fix-issue` |
| Review a PR or local change, including compatibility, tests, CI, and bot feedback | `review-pr` |
| Write regression tests | `python-tests` |
| Write or revise a docs page | `docs` |
| Evaluate a vulnerability report | `review-security-report` |
| Cut a release | `release` |

## Core MCP Objects

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

- **Tools** (`fastmcp_slim/fastmcp/tools/`)
- **Resources** (`fastmcp_slim/fastmcp/resources/`)
- **Resource Templates** (`fastmcp_slim/fastmcp/resources/`)
- **Prompts** (`fastmcp_slim/fastmcp/prompts/`)

**Before writing cross-component logic (dedupe, grouping, lookups, identity checks), read `FastMCPComponent` in `fastmcp_slim/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` and its linked guide at `docs/development/contributing.mdx` before opening issues or PRs.** The guide describes when PRs are appropriate, what we expect from enhancement proposals, and what we'll close without review.

**Review closed contributor PRs.** When reviewing an issue, inspect every associated non-maintainer PR, including closed PRs. External PRs may be closed as part of the issue-link and assignment workflow, so closure alone is not a negative signal. Read `CONTRIBUTING.md` and the PR timeline and comments to understand its status before evaluating it.

**Check unfamiliar contributors before assignment.** Follow `.agents/skills/review-issue/SKILL.md` for a brief public-history check. Avoid obvious spam or unattended bot accounts, but lean toward goodwill: account age, sparse profiles, and AI assistance alone are not reasons to reject a sound contribution.

### Git & CI

- Prek hooks are required (run automatically on commits)
- Never amend commits to fix prek failures
- Never apply labels manually or invent new ones — issues and PRs are auto-labeled by a bot based on title/body/code changes. Don't note a "suggested" or "appropriate" label anywhere in the PR body either. See the review-pr skill.
- Improvements = enhancements (not features) unless specified
- Rebase PR branches when needed. Publish rewritten history with `--force-with-lease` against the verified remote head; use an atomic push when updating a stack. Never overwrite another contributor’s new work or rewrite shared release branches. A requested rebase includes publishing it safely; it does not require separate permission for the lease-protected push.
- **ALWAYS** run applicable prek checks 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. chatgpt-codex-connector (Codex) and claude[bot] 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 <num> --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.
- **Be constructively skeptical of bot review comments on your own PRs.** Codex and claude[bot] run a fresh review pass on every push, which means a PR with active churn can accumulate bot comments in a stream that never really ends — each fix surfaces a new edge case the next pass can flag. Most of the early feedback is real and worth acting on; diminishing returns set in fast. Evaluate each comment on its merits, the same way you would a human reviewer: is this a real bug users will hit, or a hypothetical that requires an adversarial setup? Does the fix introduce more complexity than the problem? Has the bot missed context that's obvious to a human reader (a `*,` keyword-only marker, a design decision documented elsewhere, something already resolved on a later commit)? When a comment is pedantic, a false positive, or flagging something already fixed, reply on the thread explaining the reasoning and move on — don't keep iterating just because more comments arrive. If you find yourself three rounds deep and the feedback is shifting toward "what if someone does X" hypotheticals, you're past the point where each fix is improving the PR. Stop, document the contract as-is, and ship.
- **Resolve a review thread when you fix it; reply when you're declining it.** A fix explains itself through the commit, so resolving is enough — and it leaves unresolved threads meaning unfinished business, which is the signal worth having. A decline needs a one-line reason in a reply, because resolving collapses the thread and a hidden objection is worse than a visible one. Doing both is noise. Get thread ids from the GraphQL `reviewThreads` field, then resolve:

  ```bash
  gh api graphql -f query='query($n:Int!){repository(owner:"PrefectHQ",name:"fastmcp"){pullRequest(number:$n){reviewThreads(first:50){nodes{id isResolved path}}}}}' -F n=<pr-number>
  gh api graphql -f query='mutation($id:ID!){resolveReviewThread(input:{threadId:$id}){thread{isResolved}}}' -F id=PRRT_...
  ```

### Outbound Comments and Shell Interpolation

- Never pass GitHub, Linear, or Slack comment bodies inline through shell arguments when the body contains `$`, `${...}`, backticks, `$(...)`, environment-variable examples, secrets, or config interpolation examples.
- Use a body file or structured API payload for outbound comments, then inspect the exact outgoing text before posting. Prefer `gh ... --body-file /path/to/comment.md` over `--body "..."`.
- When explaining environment interpolation, use placeholders and fenced code blocks. Never include raw `.env` contents in outbound comments.

### Releases

Load the `release` skill to cut one; it holds the procedure. The policy it implements:

- Cut a release only when a maintainer asks, from the branch that owns the line: `main` for the current major, `release/3.x` or `release/2.x` for maintenance.
- Titles are `v<version>: <pun>`, with the pun on the release's main theme. Propose several and let the maintainer choose.
- The handwritten notes need the maintainer's sign-off: one or two sentences for a patch, narrative prose for a point release.
- Generate the changelog from the last stable tag (`previous_tag_name` in the notes API, or `--notes-start-tag` when using CLI generation) so a prerelease tag never truncates it. Complete contributor attribution before publication and publish those completed notes with `--notes-file`.
- Merge the docs changelog PR on the release branch immediately *before* tagging, so the entry is in the tagged commit.
- gofastmcp.com serves the `published-docs` branch, which accepts changes only through PRs.

### Commit Messages and Agent Attribution

- **Keep contributor credit focused on the community.** Maintainers are generally exempt from supplemental attribution checks. Do not add another maintainer merely for reporting, reviewing, opening the original PR, or handling a backport, and do not ask for guidance about those cases. Routine backports preserve existing community credit; they do not require a fresh attribution audit. Preserve attribution already present and proceed with the work.
- **Credit issue authors as contributors.** When acting for a maintainer and implementing a community bug report, enhancement request, or documentation issue, give the issue author co-authorship of the resulting change. Follow [Contributor credit](docs/development/contributing.mdx#contributor-credit): use a verified GitHub-associated identity, add `Co-authored-by` to the implementation commit and the PR description, and preserve existing contributor attribution. This is a required part of preparing the PR, not an optional thank-you or something the reporter must request.
- **Preserve credit through any merge strategy.** Before an authorized merge, verify the resulting commit will retain the co-author trailers. Squash merges are common here: explicitly supply a commit message containing the trailers rather than relying on GitHub's default squash message. This does not require choosing squash. Verify the landed commit after merging.
- **Carry contributor credit into releases.** Include credited issue authors alongside PR authors in release entries and include first-time contributors under `New Contributors`. GitHub's generated notes are a starting point; check and supplement them using the release skill. The same completed notes must feed the GitHub release and docs changelog.
- **Agents NOT acting on behalf of a PrefectHQ maintainer 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 (chatgpt-codex-connector, claude[bot], 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