π The fast, Pythonic way to build MCP servers and clients.
Write down triage and merge norms in docs/development (#5872)
nate nowacke1b3e575699d
diff --git a/.agents/skills/python-tests/SKILL.md b/.agents/skills/python-tests/SKILL.mdindex 9afe096f2..ba5f8bc4f 100644--- a/.agents/skills/python-tests/SKILL.md+++ b/.agents/skills/python-tests/SKILL.md@@ -5,12 +5,13 @@ description: Write regression tests for FastMCP changes using its pytest fixture# FastMCP tests-Read nearby tests and the repository's validation requirements first. Extend the owning test module when it remains readable; use a focused module when the existing one is already too large.+Read nearby tests, the [testing guide](../../../docs/development/tests.mdx), and the repository's validation requirements first. Extend the owning test module when it remains readable; use a focused module when the existing one is already too large.-For a bug fix, run the regression against unchanged code and confirm it fails for the reported reason, then run it with the fix. An import error or broken fixture is not a reproduced bug. Include supported adjacent behavior that the same branch could change, especially omitted defaults and explicit overrides.+For a bug fix, run the regression against unchanged code and confirm it fails for the reported reason, then run it with the fix. An import error or broken fixture is not a reproduced bug. To run a PR's test against main, copy it into a main worktree: `pythonpath` in pyproject shadows `PYTHONPATH`. Include supported adjacent behavior that the same branch could change, especially omitted defaults and explicit overrides.- Async tests need no marker: `asyncio_mode = "auto"` is configured globally.- Use `Client(server)` for real MCP dispatch without a network server. Use HTTP transport only when network behavior is the subject.+- Test the default protocol mode; pin `mode="legacy"` only when the handshake era is the subject.- Mock external boundaries, not the FastMCP functions under test. For OpenAPI requests, capture the outgoing request with `httpx2.MockTransport` and assert its bytes, headers, or decoded parameters.- Keep imports at module scope. Prefer function-scoped fixtures and `tmp_path` for files.- Parameterize variations of one contract; separate unrelated behavior. For JSON, equality alone does not distinguish `True` from `1`: check the resulting type when type preservation matters.diff --git a/.agents/skills/review-issue/SKILL.md b/.agents/skills/review-issue/SKILL.mdindex d5f637fba..001808f15 100644--- a/.agents/skills/review-issue/SKILL.md+++ b/.agents/skills/review-issue/SKILL.md@@ -38,11 +38,13 @@ Assignment commits us to reviewing the PR, not to merging it. A gate closure is2. **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 investigate the promised contract before escalating. Ask the maintainer only when a specific supported scenario requires a material policy choice that the protocol, docs, history, and prior decisions do not settle. Check `main`, duplicates, and prior maintainer decisions in related issues and closed PRs. If the issue is not a bug, assess its contribution category rather than treating surprising behavior alone as a defect.-3. **Check the category against [the contribution policy](../../../docs/development/contributing.mdx#choose-a-contribution).** Simple bug fixes, docs, and auth providers are assignable. Enhancements need a maintainer-approved design in the issue first; bring the precise decision and a recommendation to the maintainer, record the accepted approach, then assign. Maintainers own design opinions: do not require the contributor to obtain or settle the maintainer's preference. Once a direction is accepted, maintainers should make small corrections that align a nearly ready fix with established behavior under [review-pr](../review-pr/SKILL.md), rather than formally requesting changes for those finishing touches. Leave substantive rework to the contributor. Third-party integrations and sweeping changes without discussion are declined.+3. **Decide whether we want the change.** A real bug with a sound PR can still be one we decline. Apply [review-pr](../review-pr/SKILL.md)'s want check, covering who hits the bug, what merging commits us to, and whether docs or closing is the better answer, before recommending assignment, since assignment commits us to review.-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. Apply [review-pr](../review-pr/SKILL.md)'s behavior classification, protocol check, and competing-proposal comparison before recommending a proposal. Keep scope and design acceptance separate from implementation quality and pending validation.+4. **Check the category against [the contribution policy](../../../docs/development/contributing.mdx#choose-a-contribution).** Simple bug fixes, docs, and auth providers are assignable. Enhancements need a maintainer-approved design in the issue first; bring the precise decision and a recommendation to the maintainer, record the accepted approach, then assign. Maintainers own design opinions: do not require the contributor to obtain or settle the maintainer's preference. Once a direction is accepted, maintainers should make small corrections that align a nearly ready fix with established behavior under [review-pr](../review-pr/SKILL.md), rather than formally requesting changes for those finishing touches. Leave substantive rework to the contributor. Third-party integrations and sweeping changes without discussion are declined.-5. **Check the contributor.** For an unfamiliar account, look at its public history:+5. **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. Apply [review-pr](../review-pr/SKILL.md)'s behavior classification, protocol check, and competing-proposal comparison before recommending a proposal. Keep scope and design acceptance separate from implementation quality and pending validation.++6. **Check the contributor.** For an unfamiliar account, look at its public history:```bashgh api users/<login>@@ -50,9 +52,9 @@ Assignment commits us to reviewing the PR, not to merging it. A gate closure is--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.+ Where `users/` and search are blocked (cloud sessions), fall back to the account's history in this repo; merged history here outweighs account age. 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.+7. **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 verdictdiff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.mdindex 25bbf3d88..c55e1d482 100644--- a/.agents/skills/review-pr/SKILL.md+++ b/.agents/skills/review-pr/SKILL.md@@ -13,19 +13,21 @@ For review-only tasks, assess and report; repair, push, and monitoring steps app1. **Establish the scope.** Read AGENTS.md, the contribution policy in [the development guide](../../../docs/development/contributing.mdx), the issue's full discussion, the entire diff against the merge base, and prior review threads and replies. Record the base and head revisions. Find related issues and PRs in all states, and inspect open PRs touching the same files for overlapping lines or behavior even when they do not link the issue. Distinguish released behavior, fixes already on main, and competing proposals. When proposals compete, record the issue reporter, original implementation author, maintainer direction, correctness, and distinct coverage. Recommend which proposal should survive and preserve carried-forward credit; submission order and green CI do not select the winner. Call a sound overlapping proposal redundant rather than spurious.-2. **Establish the contract before judging the fix.** Use the protocol, released docs, history, and maintainer decisions to explain what FastMCP promises for the reported inputs. Existing code and tests are evidence of behavior, not sufficient proof that it is intended. A reproducer can demonstrate surprising behavior without demonstrating a bug; a regression test can assert the wrong result. Classify the change as a contract-restoring bug fix, intentional behavior change, public API addition or modification, documentation, or tests; a PR can span categories. Name existing inputs whose outcomes change, including defaults and explicit overrides. A bug title does not establish the category. Decide whether the behavior and ongoing support belong in FastMCP before assessing implementation quality. Resolve ordinary review uncertainty from the protocol, released docs, history, and prior maintainer decisions; make a recommendation within the established contract. Passing tests alone do not establish that contract.+2. **Decide whether we want the change at all,** per [triage and merge decisions](../../../docs/development/contributing.mdx#triage-and-merge-decisions), before verifying anything. Count a setup the reporter configured into existence, or a deprecated surface, against it. Record want / marginal / don't want with one line of reasoning and carry it into the verdict; batch reviews do this for every PR.++3. **Establish the contract before judging the fix.** Use the protocol, released docs, history, and maintainer decisions to explain what FastMCP promises for the reported inputs. Existing code and tests are evidence of behavior, not sufficient proof that it is intended. A reproducer can demonstrate surprising behavior without demonstrating a bug; a regression test can assert the wrong result. Classify the change as a contract-restoring bug fix, intentional behavior change, public API addition or modification, documentation, or tests; a PR can span categories. Name existing inputs whose outcomes change, including defaults and explicit overrides. A bug title does not establish the category. Resolve ordinary review uncertainty from the protocol, released docs, history, and prior maintainer decisions; make a recommendation within the established contract. Passing tests alone do not establish that contract.Maintainers own design opinions. Escalate only a concrete product or compatibility choice that remains unresolved after investigation and materially changes supported behavior or the scope FastMCP commits to maintaining. Identify the supported scenario, the competing outcomes, why existing authority does not settle them, and your recommended direction. Ordinary implementation judgment, naming preferences, speculative edge cases, and uncertainty that further investigation can resolve are not reasons to stop for a decision. An actual unresolved policy choice is not a contributor defect; do not submit a formal changes-requested review solely because that choice is unsettled, or ask the contributor to obtain or settle it. Once the maintainer chooses, assess the implementation against that direction. When the intended behavior is established and the correction is small, make the localized repair within authorization rather than submitting a changes-requested review. Reserve formal changes requests for a materially wrong approach or behavior that needs rethinking; explain the concrete behavioral correction after the maintainer settles the direction.For protocol-facing changes (wire fields, auth challenges, capabilities, errors, or cache semantics), cite the applicable specification revision and normative primary source. Distinguish what the protocol requires or permits, what the SDK implements or defaults, and what policy FastMCP chooses. SDK support alone does not settle framework policy; do not strengthen a protocol hint into a guarantee.-3. **Trace the cause and compatibility.** Read every changed file in context, its callers, producers and consumers, and shared abstractions. For a bug fix, state the causal ownership: the contract is X, the failure originates in Y, and this patch repairs Y. Check existing configuration, extension hooks, and shared abstractions before accepting new framework behavior. If the patch compensates elsewhere, explain why the owning layer cannot address the cause. Search for the same bug pattern and trace affected tools, resources, templates, and prompts; use canonical component identity. Compare omitted defaults, explicit overrides, errors, serialization, and supported configurations. State which existing inputs change behavior, why that is necessary, and any migration preserving the old behavior. Keep breaking changes out of a patch recommendation. Check API ergonomics, docs, and whether dependency minimums support newly used APIs; test the old minimum when compatibility is claimed and keep lockfile changes scoped.+4. **Trace the cause and compatibility.** Read every changed file in context, its callers, producers and consumers, and shared abstractions. For a bug fix, state the causal ownership: the contract is X, the failure originates in Y, and this patch repairs Y. Check existing configuration, extension hooks, and shared abstractions before accepting new framework behavior. If the patch compensates elsewhere, explain why the owning layer cannot address the cause. Search for the same bug pattern and trace affected tools, resources, templates, and prompts; use canonical component identity. Compare omitted defaults, explicit overrides, errors, serialization, and supported configurations. State which existing inputs change behavior, why that is necessary, and any migration preserving the old behavior. Keep breaking changes out of a patch recommendation. Check API ergonomics, docs, and whether dependency minimums support newly used APIs; test the old minimum when compatibility is claimed and keep lockfile changes scoped.-4. **Verify behavior independently.** For bug fixes, use [python-tests](../python-tests/SKILL.md) to run the regression on the unchanged base and proposed head yourself. Confirm it fails for the claimed reason and asserts the intended value and type, not merely that a result exists. For other changes, verify the promised behavior with appropriate checks. Exercise neighboring supported paths sharing the changed branch. For shared dispatch, security boundaries, or behavior other components rely on, get an independent adversarial pass: give a fresh agent the PR and paths to investigate, have it run reproducers in a throwaway worktree, and retain confirmed findings. Repeat that pass after substantive rework. Record revisions and checks actually run; unavailable validation remains pending evidence.+5. **Verify behavior independently.** For bug fixes, use [python-tests](../python-tests/SKILL.md) to run the regression on the unchanged base and proposed head yourself. Confirm it fails for the claimed reason and asserts the intended value and type, not merely that a result exists. For other changes, verify the promised behavior with appropriate checks. Exercise neighboring supported paths sharing the changed branch. For shared dispatch, security boundaries, or behavior other components rely on, get an independent adversarial pass: give a fresh agent the PR and paths to investigate, have it run reproducers in a throwaway worktree, and retain confirmed findings. Repeat that pass after substantive rework. Record revisions and checks actually run; unavailable validation remains pending evidence. For a merge batch, also run the composition check in [triage and merge decisions](../../../docs/development/contributing.mdx#triage-and-merge-decisions).-5. **Evaluate feedback and resolve findings.** Fetch CI, review summaries, inline threads, and replies together using the commands below. Evaluate CodeRabbit, Copilot, Codex, and maintainer feedback on its merits. Collect all independent consequential findings in one pass, with reachable triggers and consequences; do not repeat resolved or convincingly rebutted findings without new evidence. Avoid cosmetic blockers and speculative scope expansion. Within authorization, maintainer repairs should be localized finishing touches on a contribution whose scope and design are accepted and which is nearly ready. A nearly ready fix that only needs small corrections to match established behavior should be finished by the maintainer, including targeted regression coverage. After the maintainer settles the direction, substantive API, protocol, behavior, or architectural rework remains the contributor's responsibility; explain that work rather than taking over, even when maintainer edits are enabled. For the small repairs, fix real defects together, verify adjacent behavior, run required checks, and push. Resolve verified fixes; reply with a reason when declining a finding if posting is authorized. Do not iterate indefinitely on hypothetical follow-ups.+6. **Evaluate feedback and resolve findings.** Fetch CI, review summaries, inline threads, and replies together using the commands below. Evaluate CodeRabbit, Copilot, Codex, and maintainer feedback on its merits. Collect all independent consequential findings in one pass, with reachable triggers and consequences; do not repeat resolved or convincingly rebutted findings without new evidence. Avoid cosmetic blockers and speculative scope expansion. Within authorization, maintainer repairs should be localized finishing touches on a contribution whose scope and design are accepted and which is nearly ready. A nearly ready fix that only needs small corrections to match established behavior should be finished by the maintainer, including targeted regression coverage. After the maintainer settles the direction, substantive API, protocol, behavior, or architectural rework remains the contributor's responsibility; explain that work rather than taking over, even when maintainer edits are enabled. For the small repairs, fix real defects together, verify adjacent behavior, run required checks, and push. Resolve verified fixes; reply with a reason when declining a finding if posting is authorized. Do not iterate indefinitely on hypothetical follow-ups.-6. **Follow the current revision to a verdict.** A push invalidates evidence tied only to the old head. After publication or an update within the task, establish quiet monitoring using the host's scheduling capability; notify only on meaningful changes, decisions, failures, or completion, and pause after the terminal report. For a one-time review, report pending checks without creating an ongoing monitor unless requested. If persistent monitoring is unavailable, watch during the active task and state the limitation. Inspect failed CI logs before diagnosing or retrying; distinguish assertions, worker crashes, dependency resolution, and infrastructure failures. Reproduce supposedly unrelated failures on the base. Report scope and design acceptance, implementation correctness, and remaining validation separately. An approval with pending CI can be appropriate when the user has authorized it and the scope, design, and code are accepted; approval does not mean merge readiness. Pending CI cannot resolve an unsettled design decision, and a process gate is not a code defect.+7. **Follow the current revision to a verdict.** A push invalidates evidence tied only to the old head. After publication or an update within the task, establish quiet monitoring using the host's scheduling capability; notify only on meaningful changes, decisions, failures, or completion, and pause after the terminal report. For a one-time review, report pending checks without creating an ongoing monitor unless requested. If persistent monitoring is unavailable, watch during the active task and state the limitation. Confirm CI actually ran on the current head (fork runs at `action_required` need approval). Inspect failed CI logs before diagnosing or retrying; distinguish assertions, worker crashes, dependency resolution, and infrastructure failures. Reproduce supposedly unrelated failures on the base. Report scope and design acceptance, implementation correctness, and remaining validation separately. An approval with pending CI can be appropriate when the user has authorized it and the scope, design, and code are accepted; approval does not mean merge readiness. Pending CI cannot resolve an unsettled design decision, and a process gate is not a code defect.## GitHub evidence@@ -50,7 +52,9 @@ Keep the report proportional to the change, with these facts explicit:> **Verdict:** ready for maintainer consideration / changes needed / maintainer decision needed / validation pending β at `<head>`, against `<base>`.>-> **Scope and design:** change category, promised behavior and supporting source; whether it belongs in FastMCP and any precise maintainer decision still needed.+> **Want:** want / marginal / don't want, and why: who hits it, what we take on by merging.+>+> **Scope and design:** change category, promised behavior and supporting source; any precise maintainer decision still needed.>> **Implementation:** whether the patch repairs the causal layer, with consequential defects or competing-proposal selection.>@@ -62,4 +66,4 @@ Keep the report proportional to the change, with these facts explicit:## Check before finishing-Can another maintainer tell why this behavior is desirable, what existing behavior changes, and which claims were independently verified at the reported revision? If any answer is missing, qualify the verdict instead of calling the PR ready.+Can another maintainer tell whether we want this change at all, why this behavior is desirable, what existing behavior changes, and which claims were independently verified at the reported revision? If any answer is missing, qualify the verdict instead of calling the PR ready.diff --git a/.agents/skills/triage/SKILL.md b/.agents/skills/triage/SKILL.mdindex 56a4167d5..5d2315016 100644--- a/.agents/skills/triage/SKILL.md+++ b/.agents/skills/triage/SKILL.md@@ -17,7 +17,9 @@ 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.+Where `search`, GraphQL or `--paginate` are blocked (cloud sessions), page repo-scoped REST by hand (`gh api "repos/PrefectHQ/fastmcp/pulls?state=all&per_page=100&page=N"`), dump it once, and join locally.++Pick work with concrete user impact, a supported contract being violated, a tractable causal fix, and a change FastMCP wants to carry. Apply [triage and merge decisions](../../../docs/development/contributing.mdx#triage-and-merge-decisions) before ranking anything: labels and confident diagnoses are claims, and the behavior may already be fixed or decided. Mark each pick want / marginal / don't want. 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:@@ -26,6 +28,8 @@ For promising candidates:- Trace the relevant code and git history. Distinguish fixed on main, released on the affected line, and merely proposed.- Verify the claimed contract and enough evidence to explain the cause. A proposed solution is a lead, not a diagnosis. Consider compatibility before calling a fix straightforward.+For a cleanup pass, the mechanical wins are open PRs whose linked issue is already closed, issues still open after a merged "fixes #N" (check for a revert first), and competing PRs for one issue.+Lead with the strongest pick as soon as evidence supports it: link, what breaks, why it matters, where the cause is, and the next action. Include a few alternatives when useful. Do not turn selection into an exhaustive audit or a full review of every linked PR. Save continuation notes only when needed.When the user chooses implementation, use [fix-issue](../fix-issue/SKILL.md). For an assignment decision on an external contribution, use [review-issue](../review-issue/SKILL.md). Triage alone does not authorize public mutations or implementation.diff --git a/docs/development/contributing.mdx b/docs/development/contributing.mdxindex 97d184fb9..12f55cc4b 100644--- a/docs/development/contributing.mdx+++ b/docs/development/contributing.mdx@@ -109,3 +109,11 @@ The [maintenance status page](https://github.com/PrefectHQ/fastmcp/blob/status/SAutomation labels and deduplicates issues, enforces the contribution gate, explains CI failures, and checks new dependency releases nightly. Duplicate issues and reports still missing a reproduction after seven days without an author reply close automatically. Maintainers can request work with `/marvin`. A separate triage agent may open draft fixes for unclaimed issues; it does not assign contributors, comment, mark drafts ready, or merge.Maintainers decide assignments, merge readiness, changes to supported behavior or APIs, releases, and security-report classification. Release publishing and docs deployment run automatically after the corresponding maintainer actions; see [Releases](/development/releases#creating-releases).++### Triage and merge decisions++Decide whether FastMCP wants a change before verifying it. Name who hits the problem in supported, realistic usage, what merging commits the project to carrying, and whether a docs fix, a smaller fix elsewhere, or closing is the better answer. A correct, tested, green patch can still be declined.++Labels such as `high-priority` and confident diagnoses from bots or commenters are claims, not evidence. Before treating an issue as a bug, confirm its current state, since a fix may already be merged or reverted, and check whether the behavior is a decision already made in maintainer comments, closed PRs, upgrade guides, or docs. Close a settled decision with that history linked; leave a deferred design open as its tracker. When intended behavior surprises users, fix the docs or the behavior rather than adding a warning.++When PRs compete for one issue, prefer the reporter's, then the one fixing the right layer with a real regression test, then the smaller one. Before merging several PRs together, merge them onto current `main` and run the full suite and static checks there, and confirm CI actually ran on each PR's current head: fork PR runs can wait for approval, and runs older than a month cannot be re-run, so update the branch instead.diff --git a/docs/development/tests.mdx b/docs/development/tests.mdxindex aa68ccbd2..f6e1e226c 100644--- a/docs/development/tests.mdx+++ b/docs/development/tests.mdx@@ -53,6 +53,8 @@ uv run pytest -m integration --timeout=30 -n 0First establish the promised behavior from the public API, docs, protocol, and relevant maintainer decisions. A reproducible result is not automatically a bug. Once the contract is clear, run the regression on the unchanged base and confirm that it fails for the intended reason, then run it with the fix. An import error or broken fixture is not evidence of the reported defect.+To run a PR's test against unchanged code, copy the test file into a checkout of the base and run pytest there: the `pythonpath` setting in `pyproject.toml` takes precedence over `PYTHONPATH`, so pointing one checkout's tests at another checkout's source silently tests the wrong code. When a bug may depend on dependency versions, also reproduce after `uv sync --upgrade`, since the lockfile can trail what a fresh install resolves.+Assert values and types that distinguish the correct result from the bug. For example, Python equality treats `True` and `1` as equal, so a JSON type-preservation test needs a type assertion too. Avoid assertions that only check whether some result exists when the result's contents are the contract.Keep each test focused on one behavior, with as many assertions as that behavior needs. Parameterize variations of the same contract; separate unrelated cases. Include omitted defaults and explicit overrides when both enter the changed branch.@@ -215,7 +217,7 @@ async def test_two_clients_share_the_application() -> None:assert response.status_code == 404```-A test specifically about legacy MCP sessions or `ping` should pass `mode="legacy"` to the client. The modern protocol era is sessionless; see [protocol negotiation](/clients/client#protocol-negotiation). For custom client transports, `running.transport()` returns a transport wired to the same application.+Test the client's default protocol mode. A test specifically about legacy MCP sessions or `ping` should pass `mode="legacy"` to the client; pinning it elsewhere hides behavior that differs between eras. The modern protocol era is sessionless; see [protocol negotiation](/clients/client#protocol-negotiation). For custom client transports, `running.transport()` returns a transport wired to the same application.## Test external and process boundaries