π The fast, Pythonic way to build MCP servers and clients.
agents: make AGENTS.md the entry point and tighten repo skills (#5278)
nate nowack0ebabc0ceafa
diff --git a/.agents/skills/code-review/SKILL.md b/.agents/skills/code-review/SKILL.mdindex 2a2a7fb9d..3274bf971 100644--- a/.agents/skills/code-review/SKILL.md+++ b/.agents/skills/code-review/SKILL.md@@ -21,6 +21,8 @@ For dependency changes, verify the declared minimum version supports every API nReport reachable defects with concrete triggers and consequences. Evaluate bot comments on their merits; do not repeat resolved or convincingly rebutted findings without new evidence. Avoid speculative cases, cosmetic blockers, and generic requests for more tests.+When a change touches shared dispatch, a security boundary, or behavior other components rely on, also get an independent adversarial pass: give a fresh agent the PR and the paths to attack, have it run reproducers in a throwaway worktree, and keep only the findings it confirmed. Run it again after each substantive rework.+Review regression tests for the actual failure and affected neighboring contracts. Record which checks were run and at what revision. Keep uncertainty explicit: an inspected diff, a passing focused test, and a complete validated review are different evidence.Use [review-pr](../review-pr/SKILL.md) to follow CI and automated feedback after publication. A merge still needs the user's authorization and the repository's current merge gates.diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.mdindex 7b86371b4..5d3784482 100644--- a/.agents/skills/release/SKILL.md+++ b/.agents/skills/release/SKILL.md@@ -141,8 +141,8 @@ connections instead of raising.## Gotchas- `--generate-notes` copies PR titles verbatim; a title containing `<1`, `{`, or `}`- breaks MDX. `scripts/changelog_entry.py` wraps those in backticks; the validator- in step 4 catches anything it misses.+ breaks MDX, and `__name__` renders as bold. `scripts/changelog_entry.py` wraps+ those in backticks; the validator in step 4 catches anything else.- Mintlify's GitHub App also deploys on its own, but it only rebuilds fileschanged since the last commit it recorded, and it records commits it failed onor skipped. Only the `Deploy docs` run's verdict counts; its API-triggereddiff --git a/.agents/skills/release/scripts/changelog_entry.py b/.agents/skills/release/scripts/changelog_entry.pyindex 5484e48b3..3b1f857dc 100644--- a/.agents/skills/release/scripts/changelog_entry.py+++ b/.agents/skills/release/scripts/changelog_entry.py@@ -73,7 +73,10 @@ def linkify(body: str) -> str:def escape_mdx(text: str) -> str:- """Backtick-wrap bare `<digit`, `{`, `}` outside code spans; MDX reads them as JSX."""+ """Backtick-wrap MDX-sensitive text outside code spans.++ MDX reads bare `<digit`, `{`, and `}` as JSX, and `__name__` as bold.+ """def fix(line: str) -> str:parts = line.split("`")@@ -81,6 +84,9 @@ def escape_mdx(text: str) -> str:parts[i] = re.sub(r"(<\d[^\s`]*)", r"`\1`", parts[i])parts[i] = re.sub(r"(\{[^{}]*\})", r"`\1`", parts[i])parts[i] = re.sub(r"(?<!`)([{}])(?!`)", r"`\1`", parts[i])+ parts[i] = re.sub(+ r"(?<![\w`/])(__\w+?__(?:\.\w+)?)(?![\w`])", r"`\1`", parts[i]+ )return "`".join(parts)return "\n".join(fix(line) for line in text.splitlines())diff --git a/.agents/skills/review-issue/SKILL.md b/.agents/skills/review-issue/SKILL.mdindex a15e02662..a53fa06c2 100644--- a/.agents/skills/review-issue/SKILL.md+++ b/.agents/skills/review-issue/SKILL.md@@ -3,196 +3,72 @@ name: review-issuedescription: Review an incoming external issue (and any gated-closed PR behind it) and decide whether to assign the contributor or decline. Use when the maintainer says "look at this issue", "review issue #N", "should we take this", or asks whether to assign someone. Assigning the author auto-reopens their PR for normal review. This is the entry point for incoming-issue triage β distinct from review-pr, which responds to bot reviews on your own open PR.----# Triaging contributions under the issue-link gate--FastMCP gates external PRs on a valid issue link and **assignment to a referenced issue**-(see [require-issue-link.yml](../../../.github/workflows/require-issue-link.yml)). Linked PRs-stay open with a failing check while maintainers decide on assignment. PRs without a valid-issue link are closed. **The issue is the decision point**: assignment re-runs the check-and reopens previously gate-closed PRs. Inspect both open and closed contributions.--This skill turns "look at this issue" into one of two outcomes:-- **Assign** β the issue is valid, we want it fixed, an external PR is appropriate, and a sound- PR already exists β assign the author, clear the gate, and queue it for code review.-- **Decline** β recommend closing an open contribution or leaving a closed one closed,- and explain why on the issue once authorized.--Assignment is a commitment to review, not a promise to merge. Evaluate the contribution and-the contributor with goodwill. An automatic gate closure is administrative, not a rejection-on the merits; it must not raise the bar for an otherwise sound contribution.--## How the gate works (the part that matters here)--- External PRs need `Fixes/Closes/Resolves #N` and assignment to that issue. Missing links- cause closure; missing assignment alone leaves the PR open with a failing check. Issues- marked `prs welcome` waive assignment, but still require the link.-- **Assigning the author to the issue auto-reopens their closed PR** and re-runs the check β- this is the lever you pull. `gh issue edit N --add-assignee <login>`. The assignment fires a- `require-issue-link` run; expect it to pass. If it fails, the gate itself misbehaved (not the- PR) β investigate the run, don't re-assign.-- Maintainer-authored PRs are exempt. A `trusted-contributor` label exempts a contributor up- front. Reopening the PR or removing the `missing-issue-link` label applies a sticky- `bypass-issue-check`.-- Sibling bots have usually already run on the issue: `marvin-triage-issue` (investigates +- recommends), `marvin-dedupe-issues` / `auto-close-duplicates` (dupes), `auto-close-needs-mre`- (missing MRE). Read their comments before re-deriving anything.--## Step 1 β Orient--Read the issue, its bot triage, and any PR behind it. Run these together:+# Review an incoming issue-```bash-gh issue view N --repo PrefectHQ/fastmcp \- --json number,title,state,author,body,labels,assignees,comments-# Find PRs the author opened that reference this issue (they're likely CLOSED):-gh pr list --repo PrefectHQ/fastmcp --state all --search "author:<login> #N in:body" \- --json number,title,state,url,labels-```+This skill ends in one of two recommendations for the maintainer:-If a PR exists, pull its metadata and any review-bot comments (CodeRabbit, Codex). Treat the bot-comments as leads, not conclusions β they often don't run on closed PRs at all, and even when-they do you still owe the PR your own read:+- **Assign**: the issue is valid, an external PR suits it, and a sound PR exists. Assign the author, which clears the gate, then review the code.+- **Decline**: close the open contribution, or leave a closed one closed, and explain why on the issue once authorized.-```bash-gh pr view <pr> --repo PrefectHQ/fastmcp --json number,title,body,labels,files,additions,deletions-gh pr view <pr> --repo PrefectHQ/fastmcp --comments-```+Assignment commits us to reviewing the PR, not to merging it. A gate closure is administrative, so a closed PR gets the same bar as an open one.-### Check the contributor before assignment+## How the gate works-Make a brief public-account check before assigning an unfamiliar contributor. Look at account-age, a sample of contributions elsewhere, and how they respond to review. Merged fixes and-substantive exchanges with maintainers are useful evidence of follow-through. GitHub's `User`-account type does not establish that a human operates the account.+[require-issue-link.yml](../../../.github/workflows/require-issue-link.yml) checks every external PR:-```bash-gh api users/<login>-gh search prs --author <login> --limit 20 --sort created --order desc \- --json repository,title,state,createdAt,url-```+- It needs `Fixes/Closes/Resolves #N`. PRs without a valid link are closed.+- A linked PR stays open with a failing check until its author is assigned to that issue. Issues labeled `prs welcome` waive assignment but still need the link.+- Assigning the author (`gh issue edit N --add-assignee <login>`) re-runs the check and reopens a gate-closed PR. If that run fails, the gate misbehaved: investigate the run rather than re-assigning.+- Maintainer PRs are exempt, and so are authors with the `trusted-contributor` label. Reopening a PR by hand or removing `missing-issue-link` applies a sticky `bypass-issue-check`, so prefer assignment.+- `marvin-triage-issue`, `marvin-dedupe-issues`, `auto-close-duplicates`, and `auto-close-needs-mre` have usually commented already. Read them as leads.++## Procedure++1. **Orient.** Read the issue, its bot comments, and every PR that references it, in all states:++ ```bash+ gh issue view N --repo PrefectHQ/fastmcp \+ --json number,title,state,author,body,labels,assignees,comments+ gh pr list --repo PrefectHQ/fastmcp --state all --search "#N in:body" \+ --json number,title,state,author,url,labels+ gh pr view <pr> --repo PrefectHQ/fastmcp --json title,body,labels,files,additions,deletions+ gh pr view <pr> --repo PrefectHQ/fastmcp --comments+ ```++2. **Decide whether the issue describes a bug.** Reproduce the MRE, then ask whether the behavior violates a contract FastMCP intends to hold. Behavior that only appears by mutating construction-time state or relying on internals is a property of the code, not a defect. The code shows what FastMCP does, not what it promises, so ask the maintainer "is X supported?" when the contract is unclear. Check `main`, duplicates, and prior maintainer decisions in related issues and closed PRs. If the issue is not a bug, recommend declining without reviewing the PR.-Avoid assigning obvious spam or unattended bot accounts: look for concrete patterns such as-mass unrelated boilerplate, repeated nonresponsive replies, or explicit unattended automation.-A new account, sparse profile, low follower count, or disclosed AI assistance alone is not a-reason to decline. Do not demand identity proof or infer legitimacy from profile claims alone.-When evidence is limited, say so and lean toward goodwill for a sound, scoped contribution;-bring a material concern to the maintainer before assigning.--## Step 2 β Classify the issue (is it valid AND a real bug?)--- Is there a real, reproducible problem? For bugs, demand an MRE that shows FastMCP misbehaving- β not user config error, not a question, not an upstream-SDK issue.-- Is it a duplicate or already fixed on `main`? Check the dedupe bot's comment and recent commits.-- Search earlier issues, PRs (including closed ones), and relevant git history before deciding.- Read maintainer decisions and why prior approaches were accepted or rejected.-- If the issue itself is weak, **stop here and decline** β don't evaluate the PR. A good PR- attached to a bad issue is still declined.--**A reproducible MRE is not the same as a bug.** This is the trap that produces wrong verdicts:-an MRE can demonstrate real, observable behavior that is nonetheless *not a bug*, because it-violates no contract the framework intends to hold. The decisive question is not "does this-reproduce?" but "does the demonstrated behavior violate the intended contract for this API?" A-shared-mutable-state MRE only matters if callers are *supposed* to mutate that state; an-ordering/timing MRE only matters if the framework promises an order; a "wrong" value only matters-relative to what the API guarantees. An MRE that has to reach past the supported surface to-trigger the behavior (mutating a field meant to be set only at construction, depending on an-internal that isn't part of the public contract) is showing you a property, not a defect.--You usually cannot read the intended contract off the code β the code shows what it *does*, not-what it *promises*. **The maintainer is often the only authoritative source for the contract, so-stopping to ask is legitimate and expected here.** Ask "is X a supported pattern / does this API-promise Y?" before sinking time into investigating a fix. If the behavior is in-contract correct,-decline β no matter how cleanly the PR fixes it, and no matter how real the MRE looks.--## Step 3 β Investigate the PR (mandatory; do NOT skip if a PR exists)--The most common failure of this skill is judging a PR from the diff hunk and the PR description-alone. That is a cursory review and it produces wrong verdicts β a redundant-looking conditional-can be a real bug fix; a tidy-looking diff can patch the wrong layer. **You cannot assess a PR-without reading the code it changes in context.** Reading `gh pr diff` is necessary but never-sufficient.--Do all of this before forming any opinion on quality:--1. **Read the diff in full**, then **open every file it touches in the repo** (`Read`, not just- the patch). The hunk shows *what changed*; the file shows *what it changed into*.-2. **Trace the functions and values the change depends on.** Grep for the called functions,- the fields being set, and the defaults. If the PR overrides or replaces a value, find what- produced the original value and what consumes it downstream.-3. **Establish the actual root cause from the issue's MRE**, then check whether the change fixes- *that* β at the layer where the bug originates, not a compensating patch elsewhere.-4. **Check consistency with adjacent code.** Does the new value/behavior match how nearby code- already handles the same case? An inconsistency is a real finding; a match is evidence the fix- is correct.-5. **Run or read the tests** the PR adds/changes β do they actually exercise the bug, and would- they fail without the fix?--Write down, for yourself, a one-line answer to: *what was broken, where, and does this change fix-it there?* If you can't answer from evidence you've actually read, you haven't investigated yet.--Then separate findings by severity: a **cosmetic** nit (style, a redundant-but-harmless line) is a-review comment, not a blocker. A **substantive** defect (wrong layer, breaks an adjacent path,-doesn't actually fix the MRE) changes the verdict. Don't let a cosmetic nit read as a reason to-decline, and don't let a clean style read as evidence of correctness.--## Step 4 β Decide if an external PR is appropriate (CONTRIBUTING.md)--This is the gate CONTRIBUTING.md actually enforces. Map the change to a category:--- **Simple, well-scoped bug fix** β external PR welcome. Assignable.-- **Docs / typo / example fix** β welcome. Assignable.-- **Auth provider** β assignable (auth is the one integration exception).-- **Enhancement / feature** β needs a maintainer-approved design proposal *in the issue first*.- Do **not** assign just because code exists. If the proposal is sound, the path is "approve the- approach in the issue, then assign" β not "assign because they were fast."-- **Third-party integration** (middleware, provider adapters, non-auth) β decline; belongs in a- separate package.-- **Sweeping / multi-subsystem change with no prior discussion** β decline.--Combine the category with the Step 3 investigation: does it fix the cause or paper over a symptom?-Does it read like unedited LLM output (verbose body, speculative/shotgun changes)? CONTRIBUTING.md-says we close those β a closed PR that reads that way is staying closed.--## Step 5 β Recommend, then act--Present a short verdict to the maintainer before mutating anything: **assign** or **decline**,-one or two sentences of reasoning, and the exact command you'll run. Act within the maintainer's-existing authorization; do not ask again for an action already approved. Bring borderline-calls back to the maintainer, and obtain approval for public actions not yet authorized.--**Assign** (valid issue + appropriate external contribution + sound PR exists):+3. **Check the category against CONTRIBUTING.md.** Simple bug fixes, docs, and auth providers are assignable. Enhancements need a maintainer-approved design in the issue first; approve the approach, then assign. Third-party integrations and sweeping changes without discussion are declined.++4. **Investigate the PR in context.** Read the full diff, then open each touched file. Trace the values and functions it changes to where they are produced and consumed. From the MRE, state in one line what was broken, where, and whether this change fixes it there. Compare with how adjacent code handles the same case, and check that the tests fail without the fix. Treat style issues as review comments; a wrong layer, a broken adjacent path, or an unfixed MRE changes the verdict.++5. **Check the contributor.** For an unfamiliar account, look at its public history:++ ```bash+ gh api users/<login>+ gh search prs --author <login> --limit 20 --sort created --order desc \+ --json repository,title,state,createdAt,url+ ```++ Merged fixes elsewhere and substantive replies to reviewers show follow-through. Decline obvious spam or unattended automation: mass unrelated boilerplate, repeated nonresponsive replies. A new account, a sparse profile, or disclosed AI assistance is not a reason to decline. When evidence is thin, lean toward goodwill for a sound, scoped contribution and mention the uncertainty.++6. **Recommend.** Give the maintainer the verdict, one or two sentences of reasoning, and the exact command. Act within existing authorization and bring borderline calls back.++## Acting on the verdict++**Assign:**```bashgh issue edit N --repo PrefectHQ/fastmcp --add-assignee <login>```-Verify that the assignment workflow clears the check and reopens the PR if it was closed.-If it does not, inspect the run and the PR timeline. When reopening is authorized and the gate caused the closure, reopen the-existing PR; do not override a substantive maintainer closure. A manual reopen applies the-workflow's sticky bypass, so prefer the normal assignment path and do not manipulate labels.--Then hand off to code review β invoke the `code-review` /-`review-pr` skills on the reopened PR. Assignment is not approval; the code still gets the normal-pass.+Confirm the `require-issue-link` run passes and the PR reopens, then review it with [code-review](../code-review/SKILL.md) and follow it with [review-pr](../review-pr/SKILL.md). If the PR's head branch was deleted, assignment cannot reopen it; the workflow asks the author for a fresh PR.-If a PR's head branch was deleted, assignment can't reopen it β the workflow comments asking the-author to open a fresh PR. Don't try to force it.--**Decline** (invalid issue, wrong contribution type, or low-quality PR): with authorization,-close the open contribution or leave it closed and comment on the **issue** explaining the decision, pointing to the relevant CONTRIBUTING.md-section. Per repo rules, use `--body-file`, never inline `--body`, for any comment that could-contain `$`, backticks, or code:+**Decline:** with authorization, comment on the issue with the reason and the relevant CONTRIBUTING.md section. Write the body to a file first:```bashgh issue comment N --repo PrefectHQ/fastmcp --body-file /tmp/triage-reply.md```-Keep the reply short and point to the relevant CONTRIBUTING.md section. (If a `github-reply`-skill is available for maintainer voice/tone, use it β but it isn't required.)--## What this skill does NOT do+## Check before finishing-- It doesn't grant blanket trust via `trusted-contributor` or manually apply bypass labels.- An explicitly authorized reopen of a gate-closed PR is scoped to that PR.-- It doesn't merge. Assignment β reopen β review β (maybe) merge are distinct steps.-- It doesn't re-run the first-pass triage the bots already did; read their output instead.+The recommendation names the contract the issue does or does not violate, the layer where the cause lives, and whether the PR fixes it there.diff --git a/.agents/skills/triage/SKILL.md b/.agents/skills/triage/SKILL.mdindex df48fe07c..b32ef5858 100644--- a/.agents/skills/triage/SKILL.md+++ b/.agents/skills/triage/SKILL.md@@ -7,6 +7,16 @@ description: Find worthwhile FastMCP issues to work on in a backlog or release wRead AGENTS.md and CONTRIBUTING.md. Honor the requested scope. For "since the last patch," identify the release timestamp, then look for open issues created or substantively updated afterward. Use a bounded inventory internally; report truncation if it affects coverage.+Start from an inventory, then link each candidate to the PRs that mention it:++```bash+gh release list --repo PrefectHQ/fastmcp --limit 1+gh issue list --repo PrefectHQ/fastmcp --state open --limit 30 \+ --json number,title,author,createdAt,updatedAt,labels,comments+gh pr list --repo PrefectHQ/fastmcp --state all --search "<issue-number> in:body" \+ --json number,title,state,author+```+Pick work with concrete user impact, a supported contract being violated, and a tractable causal fix. Do not rank solely by recency, comment count, or how small a proposed patch looks. Automated dashboard churn is not itself useful work.For promising candidates:diff --git a/.github/scripts/test-ci-workflows.mjs b/.github/scripts/test-ci-workflows.mjsindex 72ea73f89..3c9e10ea0 100644--- a/.github/scripts/test-ci-workflows.mjs+++ b/.github/scripts/test-ci-workflows.mjs@@ -108,7 +108,7 @@ for (const filename of ["docs/script.js","docs/snippets/example.py","new-package/README.md",- "CLAUDE.md",+ "AGENTS.md",]) {test(`full coverage with mixed changes: ${filename}`, async () => {assert.equal(diff --git a/.github/workflows/marvin-dedupe-issues.yml b/.github/workflows/marvin-dedupe-issues.ymlindex f5a8c7b17..02b65fd77 100644--- a/.github/workflows/marvin-dedupe-issues.yml+++ b/.github/workflows/marvin-dedupe-issues.yml@@ -19,12 +19,9 @@ jobs:issues: writeid-token: write- # TEMPORARY PIN β see the matching note in marvin-label-triage.yml.- # Claude Code 2.1.216 broke every Bash call under the action's subprocess- # isolation, which this workflow needs for all of its `gh` searching.- # https://github.com/anthropics/claude-code/issues/79997+ # Pinned Claude Code; see the matching note in marvin-label-triage.yml.env:- PINNED_CLAUDE_CODE_VERSION: "2.1.215"+ PINNED_CLAUDE_CODE_VERSION: "2.1.282"steps:- name: Checkout repositorydiff --git a/.github/workflows/marvin-label-triage.yml b/.github/workflows/marvin-label-triage.ymlindex f12f0f096..2c462329e 100644--- a/.github/workflows/marvin-label-triage.yml+++ b/.github/workflows/marvin-label-triage.yml@@ -35,21 +35,14 @@ jobs:issues: writepull-requests: write- # TEMPORARY PIN β remove once upstream ships a fix.- #- # Claude Code 2.1.216 regressed the sandbox that claude-code-action wraps- # every Bash call in when `allowed_non_write_users` is set: the mountpoint- # walk fails closed, so every command β down to `true` β dies with- # `bwrap: Can't create file at /home/.mcp.json: Permission denied`.- # Marvin still reads the issue and picks correct labels, then cannot run- # the helper that applies them, so triage silently applied zero labels- # from 2026-07-20 onward while every run reported success.- #- # 2.1.215 is the last release without the regression.+ # Pinned Claude Code. The repository instructions are AGENTS.md, which+ # Claude Code reads natively from 2.1.281 on. Releases 2.1.216 through+ # 2.1.226 broke every Bash call under the action's sandbox (`bwrap: Can't+ # create file at /home/.mcp.json`), which let triage apply zero labels+ # while reporting success; the sandbox check below fails the run instead.# https://github.com/anthropics/claude-code/issues/79997- # https://github.com/anthropics/claude-code-action/issues/1547env:- PINNED_CLAUDE_CODE_VERSION: "2.1.215"+ PINNED_CLAUDE_CODE_VERSION: "2.1.282"steps:- name: Checkout base repositorydiff --git a/AGENTS.md b/AGENTS.mddeleted file mode 120000index 681311eb9..000000000--- a/AGENTS.md+++ /dev/null@@ -1 +0,0 @@-CLAUDE.md\ No newline at end of filediff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 000000000..acd90264a--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,192 @@+# 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++**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 |+| ----------------- | -------------------------------------- |+| `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/`, with symlinks in `.claude/skills/` for Claude Code. Load the one 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 change, yours or a contributor's | `code-review` |+| Follow a PR through CI and bot review | `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` before opening issues or PRs.** It 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+- **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 <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.** CodeRabbit, 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.+- Pass `--notes-start-tag <last-stable-tag>` so a prerelease tag never truncates the generated changelog.+- 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++- **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 (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++- **Do not create overeager `__init__.py` files.** Package initializers should not import heavy submodules, provider stacks, optional integrations, or modules that can point back into the package. Overeager re-exports make the framework sprawl and create circular imports that only appear in fresh interpreters or clean installs.+- **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 `fastmcp_slim/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 `fastmcp_slim/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.++## Code Review Rules++### Framework regressions and root causes++- Review changes carefully for regressions in supported framework behavior, including interactions beyond the immediate diff. Trace relevant callers, shared abstractions, protocol and public API contracts, and all affected MCP component types. Determine whether a change fixes the causal code path or merely compensates for the symptom; side channels and special cases that leave the root cause intact should be treated as suspect.++### Comprehensive first pass++- Review the entire pull request diff against the merge base, not only the latest commits. Inspect every changed file and the relevant surrounding code, collect all independent, substantiated consequential findings before submitting the review, and report the complete set in one review whenever possible. Do not stop after finding the first few issues or defer other already-visible findings to later review cycles.++### Prior discussion and proportionality++- When prior review threads and author or maintainer replies are available, read them before commenting. Evaluate responses on their merits and do not repeat a resolved or convincingly rebutted finding without new evidence. Avoid fixating on speculative edge cases: report an edge case only when it is reachable under supported usage or a credible threat model and has meaningful impact; otherwise omit it or clearly treat it as non-blocking.++## 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 testsdiff --git a/CLAUDE.md b/CLAUDE.mddeleted file mode 100644index 6a6224853..000000000--- a/CLAUDE.md+++ /dev/null@@ -1,214 +0,0 @@-# 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 |-| ----------------- | -------------------------------------- |-| `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) |--## 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 `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` before opening issues or PRs.** It 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-- **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 <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.** CodeRabbit, 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--The executable procedure lives in `.agents/skills/release/SKILL.md`; load that skill to cut one. The policy below is the contract it implements.--Only cut releases when the maintainer explicitly asks. Tags follow `v<version>` (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<version>: <pun>` 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 v4.0.0 --target main --title "v4.0.0: Theme Here" --generate-notes --notes-start-tag v3.4.4 --notes-file /tmp/release-notes.md-```--**Always pass `--notes-start-tag <last-stable-tag>`.** Without it, `--generate-notes` picks the most recent prior tag as the changelog start point β and if a prerelease exists (e.g. `v3.4.0b1`), it starts from *that*, silently truncating the PR list to only the commits since the beta. Pin it to the last stable release (e.g. `v3.3.1` when cutting `v3.4.0`). Verify after: the compare link at the bottom of the generated notes should read `v<last-stable>...v<new>`.--Use the branch that owns the release line as the target: current-major releases target `main`, 3.x maintenance releases target `release/3.x`, and 2.x maintenance releases target `release/2.x`. Confirm the target with the maintainer if there's any ambiguity. For example, cut a 3.4.4 maintenance release with `--target release/3.x`, not `main`.--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 <tag>`) 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'-```--Set `target_commitish` to the same branch that will receive the release tag. For maintenance releases, use the maintenance branch (for example, `release/3.x`) so the preview matches the release notes GitHub will generate.--**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.--**Publish docs through a PR.** The `published-docs` branch serves gofastmcp.com, and repository rules reject direct pushes and force-pushes to it. Stable releases from `main` automatically open a publication PR after PyPI succeeds. For prereleases and later docs follow-ups, create the same PR manually: start a temporary branch from the current `published-docs`, make a single commit whose tree exactly matches the desired commit on `main`, and use `published-docs` as the PR base. Merging publishes to production. Never push directly to `published-docs`.--**Merge the docs changelog PR *before* cutting the release, not after.** The post-publish `update-published-docs` job opens a PR that syncs `published-docs` to the released commit for stable releases on the default branch, so the changelog entry only reaches the live site if it's already in the commit being tagged. Land the docs PR on the release target branch first, then cut the release from that branch. If you tag first and merge docs after, this release's publication PR will not include the changelog; publish `main` manually through the PR flow above or wait for the next default-branch stable release. Maintenance releases from `release/3.x` or `release/2.x` publish packages and GitHub notes without repointing `published-docs`; add their changelog entries on the maintenance branch, slotted into the matching major-version section. Two hand-maintained files mirror the GitHub release and must get a new entry for every version, newest at the top (these are `.mdx` and are not covered by the prek Prettier hook, which only runs on `yaml`/`json5` β match the existing entries' style by hand):--- `docs/changelog.mdx` is the full mirror. Add an `<Update label="v<version>" description="YYYY-MM-DD">` block with: a bold linked title (`**[v<version>: <pun>](<release-url>)**`), a condensed 1-paragraph intro (one sentence for patches), the full categorized PR list reformatted from the `--generate-notes` output (`* <title> by [@user](https://github.com/user) in [#NNNN](<pull-url>)`), a `## New Contributors` list (plain `@user`, linked PR), and a `**Full Changelog**: [vA...vB](<compare-url>)` line.-- `docs/updates.mdx` is the skimmable card feed. Add an `<Update label="FastMCP <version>" description="Month DD, YYYY" tags={["Releases"]}>` wrapping a `<Card>` that links to the GitHub release, with a 1-2 sentence summary and (for point releases) a handful of emoji-bulleted highlights.--Because the docs land *before* the tag exists, derive the entry from the maintainer-approved handwritten notes (intro/summary) and the `--generate-notes` API *preview* (the PR-list body β see the generate-notes API call above, which returns the exact changelog without cutting anything). Scripting the link reformatting is reliable for long PR lists. The release-URL, tag, and compare links follow the known pattern (`/releases/tag/v<version>`, `compare/v<last-stable>...v<version>`) and will 404 only during the short window between merging the docs PR and cutting the release minutes later β they resolve before the release workflow completes. For this reason, create and merge the docs PR *immediately* before cutting the release β treat the two as one tight back-to-back sequence, not independent steps β so the links are valid by the time the release publishes rather than dangling for any longer than necessary.--### Commit Messages and Agent Attribution--- **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 (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--- **Do not create overeager `__init__.py` files.** Package initializers should not import heavy submodules, provider stacks, optional integrations, or modules that can point back into the package. Overeager re-exports make the framework sprawl and create circular imports that only appear in fresh interpreters or clean installs.-- **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 `fastmcp_slim/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 `fastmcp_slim/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.--## Code Review Rules--### Framework regressions and root causes--- Review changes carefully for regressions in supported framework behavior, including interactions beyond the immediate diff. Trace relevant callers, shared abstractions, protocol and public API contracts, and all affected MCP component types. Determine whether a change fixes the causal code path or merely compensates for the symptom; side channels and special cases that leave the root cause intact should be treated as suspect.--### Comprehensive first pass--- Review the entire pull request diff against the merge base, not only the latest commits. Inspect every changed file and the relevant surrounding code, collect all independent, substantiated consequential findings before submitting the review, and report the complete set in one review whenever possible. Do not stop after finding the first few issues or defer other already-visible findings to later review cycles.--### Prior discussion and proportionality--- When prior review threads and author or maintainer replies are available, read them before commenting. Evaluate responses on their merits and do not repeat a resolved or convincingly rebutted finding without new evidence. Avoid fixating on speculative edge cases: report an edge case only when it is reachable under supported usage or a credible threat model and has meaningful impact; otherwise omit it or clearly treat it as non-blocking.--## 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 testsdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 51cef380c..1166c9181 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -20,6 +20,8 @@ That's it. No need to diagnose root causes, propose API designs, or suggest implWe encourage you to use LLMs to help identify bugs, write MREs, and prepare contributions. But if you do, your LLM must take into account the conventions and contributing guidelines of this repo β including how we want issues formatted and when it's appropriate to open a PR. Generic LLM output that ignores these guidelines tells us the contribution wasn't made thoughtfully, and we will close it. A good AI-assisted contribution is indistinguishable from a good human one. A bad one is obvious.+Start your agent from [AGENTS.md](AGENTS.md). It holds the development workflow, the required checks, and the conventions reviewers expect. The repository also ships skills in [`.agents/skills/`](.agents/skills/) (linked into `.claude/skills/` for Claude Code) that walk an agent through common jobs: `fix-issue` carries a bug from reproduction to a PR, `python-tests` covers the test conventions, `docs` covers documentation pages, and `code-review` is the review your PR will get, so run it on your own change before opening one.+If you're driving an agent: do **not** have it post comments asking to be assigned to an issue or announcing that it intends to work on one. Those comments are ignored. If the agent intends to contribute, open a PR instead β it will be gated on assignment (see below). Comment on an issue only to propose a genuinely novel, differentiated solution, never to claim a task that's already described.## When to open a pull request@@ -54,6 +56,10 @@ If you do open a PR:- **Fix the cause, not the symptom.** If the bug is that a code path skips a step, the fix should make it stop skipping that step β not add compensation elsewhere. Workaround-style fixes will be sent back for revision.- **Don't submit generated boilerplate.** We review every line. PRs that read like unedited LLM output β verbose descriptions, speculative changes, shotgun-style fixes β will be closed.+## Maintaining FastMCP++Maintainers use the same skills for the rest of the project's work: `triage` finds worthwhile issues, `review-issue` decides whether to assign an external contributor, `review-pr` follows a PR through CI and bot review, `review-security-report` evaluates vulnerability reports, and `release` cuts a release from notes preview to a verified docs deploy. The table in [AGENTS.md](AGENTS.md#skills) maps each job to its skill. Skills stop before public actions such as commenting, assigning, merging, or tagging, and ask the maintainer driving them.+## What we'll close without reviewTo keep the project maintainable, we will close PRs that: