Sync main to published-docs

.claude/skills/code-review/SKILL.md

@@ -19,6 +19,13 @@ Be friendly and welcoming while maintaining high standards. Call out what works
 
 Even perfect code for unwanted features should be rejected.
 
+### Dependency version compatibility
+
+When a PR adapts code to a new version of a dependency (e.g., removing a parameter that was dropped upstream, using a new API):
+- **The version pin in `pyproject.toml` must match.** If the change breaks compatibility with the previously-pinned minimum version, the minimum version must be bumped. Otherwise users on the old version get a regression.
+- **If backwards compatibility with the old version is desired**, the code must handle both versions (e.g., try/except, version check). Simply deleting the old API usage without bumping the pin is always wrong — it silently breaks users on the old version.
+- **Lock file (`uv.lock`) changes should be scoped to the PR's purpose.** A PR fixing a ty compatibility issue should not also include unrelated dependency version bumps (anthropic, google-auth, etc.) from running `uv sync --upgrade`. These create noise and make the diff harder to review.
+
 ### API design and naming
 
 Identify confusing patterns or non-idiomatic code:

.claude/skills/review-pr/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: review-pr
+description: Monitor and respond to automated PR reviews (Codex bot). Use when pushing a PR, checking review status, or responding to bot feedback. Handles the full cycle of push -> wait for review -> evaluate comments -> fix -> re-push.
+---
+
+# PR Review Workflow
+
+This repo has `chatgpt-codex-connector[bot]` configured as an automated reviewer. After every push to a PR branch, Codex reviews the diff and either:
+- Reacts with a thumbs-up on its review body (no suggestions — PR is clean)
+- Posts inline comments with suggestions (each tagged with a priority badge)
+
+## Checking review status
+
+After pushing, check whether Codex has reviewed the latest commit:
+
+```bash
+# Get the latest commit SHA on the branch
+LATEST=$(git rev-parse HEAD)
+
+# Check if Codex has reviewed that specific commit
+gh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/reviews \
+  | jq "[.[] | select(.user.login == \"chatgpt-codex-connector[bot]\" and .commit_id == \"$LATEST\")] | length"
+```
+
+If the count is 0, Codex hasn't reviewed the latest push yet. Wait and check again.
+
+If the count is > 0, check for inline comments on the latest review:
+
+```bash
+# Get the review body to check for thumbs-up
+gh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/reviews \
+  | jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]") | {state, body: .body[:300], commit_id: .commit_id}] | last'
+```
+
+A clean review from Codex looks like a review body that contains a thumbs-up reaction or says "no suggestions." If the body contains "Here are some automated review suggestions," there are inline comments to evaluate.
+
+## Evaluating Codex comments
+
+Fetch all inline comments from Codex:
+
+```bash
+gh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/comments \
+  | jq '[.[] | select(.user.login == "chatgpt-codex-connector[bot]") | {body, path, line, created_at}]'
+```
+
+Codex comments include priority badges:
+- `P0` (red) — Critical issue, likely a real bug
+- `P1` (orange) — Important, worth fixing
+- `P2` (yellow) — Moderate, evaluate on merit
+
+**How to evaluate Codex comments:**
+
+1. **Treat Codex as a competent but sometimes overzealous reviewer.** It catches real bugs (cache eviction ordering, silent data loss, missing validation) but also suggests scope expansions and hypothetical improvements.
+
+2. **Fix real bugs** — issues in code you actually changed where behavior is incorrect or data is silently lost.
+
+3. **Dismiss scope expansion** — if a comment points out a pre-existing limitation unrelated to your diff, note it as a potential follow-up but don't block the PR.
+
+4. **Dismiss speculative concerns** — if a comment describes a scenario that requires very specific conditions and the existing behavior is acceptable, dismiss it.
+
+5. **When fixing, be proactive** — if Codex found one instance of a pattern bug (e.g., missing role validation in one handler), check all similar code paths before pushing. Codex will find the next instance on the next review cycle, so get ahead of it.
+
+## Responding to every comment
+
+**Every Codex comment must get a visible response** — either a fix or a reply explaining why it was dismissed. The maintainer can't see your reasoning otherwise.
+
+- **If fixing**: The fix itself is the response. No reply needed unless the fix is non-obvious.
+- **If dismissing**: Reply to the comment thread with a brief explanation of why. Keep it to 1-2 sentences. Examples:
+  - "This is pre-existing behavior unrelated to this diff — the scope lookup fallback existed before caching was added. Worth a follow-up issue but not blocking this PR."
+  - "The AsyncExitStack handles cleanup when the session exits, so the subprocess isn't leaked — just kept alive slightly longer than necessary in this edge case."
+  - "Gemini supports a much wider range of media types than OpenAI/Anthropic, so a restrictive allowlist would be inaccurate here."
+
+Use `gh api` to reply (note: use `in_reply_to`, not a `/replies` sub-path):
+
+```bash
+# Reply to a specific review comment
+gh api repos/PrefectHQ/fastmcp/pulls/{PR_NUMBER}/comments \
+  -f body="Your reply here" \
+  -F in_reply_to={COMMENT_ID}
+```
+
+## The fix-push-review cycle
+
+After evaluating comments:
+
+1. Fix all real issues in one batch
+2. Reply to all dismissed comments with reasoning
+3. Think about what patterns Codex might flag next — check similar code paths proactively
+4. Commit and push
+5. Check that Codex reviews the new commit
+6. Repeat until Codex gives a clean review (thumbs-up) or only has dismissible comments
+
+## Responding to stale comments
+
+Codex sometimes re-posts old comments that reference code you've already fixed (they appear on the old commit's diff). These are stale — verify the fix is in the latest commit and reply noting the fix is already in place.
+
+## When a PR is ready
+
+A PR is ready for human review when:
+- All Codex comments are either fixed or replied to with dismissal reasoning
+- CI checks pass
+- The diff is clean and focused on the stated purpose

.github/ISSUE_TEMPLATE/bug.yml

@@ -3,33 +3,30 @@ description: Report a bug or unexpected behavior in FastMCP
 labels: [bug, pending]
 
 body:
-  - type: markdown
-    attributes:
-      value: Thanks for contributing to FastMCP! 🙏
-
   - type: markdown
     attributes:
       value: |
-        ### Before you submit
+        Thanks for reporting a bug!
 
-        To help us help you, please:
+        A good bug report is one of the most valuable contributions you can make — see [CONTRIBUTING.md](../../CONTRIBUTING.md). If the fix is straightforward, a PR is also welcome.
 
-        - 🔄 **Make sure you're testing on the latest version of FastMCP** - many issues are already fixed in newer versions
-        - 🔍 **Check if someone else has already reported this issue** or if it's been fixed on the main branch
-        - 📋 **You MUST include a copy/pasteable and properly formatted MRE** (minimal reproducible example) below or your issue may be closed without response
-        - 💡 **The ideal issue is a clear problem description and an MRE — that's it.** If you've done a genuine investigation and have a non-obvious insight into the root cause, include it. But please don't speculate or ask an LLM to generate a diagnosis or proposed fix. We have LLMs too, and an incorrect analysis is harder to work with than none at all.
-        - ✂️ **Keep it short.** A one-paragraph description and a working MRE is the ideal bug report. Issues that are difficult to parse — due to length, speculation, or generated content — may be closed without response.
+        ### Before you submit
 
-        Thanks for helping to make FastMCP better! 🚀
+        - Make sure you're testing on the **latest version** of FastMCP — many issues are already fixed in newer releases
+        - Check if someone else has **already reported this** or if it's been fixed on the main branch
+        - You **must** include a copy/pasteable, properly formatted MRE (minimal reproducible example) or your issue may be closed without response
+        - **The ideal issue is a clear problem description and an MRE — that's it.** If you've done genuine investigation and have a non-obvious insight into the root cause, include it. But please don't speculate or ask an LLM to generate a diagnosis. We have LLMs too, and an incorrect analysis is harder to work with than none at all.
+        - **Keep it short.** A clear description plus a concise MRE is ideal — aim to fit in a single screen. Issues that include unsolicited root cause analysis, proposed fixes, or multi-section diagnostic writeups will be labeled `too-long` and not triaged until condensed.
+        - **Using an LLM?** Great — but it must follow these guidelines. Generic LLM output that ignores our contributing conventions will be closed. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
   - type: textarea
     id: description
     attributes:
-      label: Description
+      label: What happened?
       description: |
-        Please explain what you're experiencing and what you would expect to happen instead.
+        Describe the bug in a few sentences. What did you do, what happened, and what did you expect instead?
 
-        Provide as much detail as possible to help us understand and solve your problem quickly.
+        Do NOT include root cause analysis, proposed fixes, or diagnostic writeups — just describe the problem.
     validations:
       required: true
 

.github/ISSUE_TEMPLATE/enhancement.yml

@@ -3,33 +3,27 @@ description: Suggest an idea or improvement for FastMCP
 labels: [enhancement, pending]
 
 body:
-  - type: markdown
-    attributes:
-      value: Thanks for contributing to FastMCP! 🙏
-
   - type: markdown
     attributes:
       value: |
-        ### Before you submit
+        Thanks for suggesting an improvement to FastMCP!
 
-        To help us evaluate your enhancement request:
+        Enhancement issues are the **primary way** features and improvements get into FastMCP. Maintainers use well-written issues to implement changes that fit the codebase's patterns and ship quickly. A clear issue here is more impactful than a PR — see [CONTRIBUTING.md](../../CONTRIBUTING.md) for why.
 
-        - 🔍 **Check if this has already been requested** - search existing issues first
-        - 💭 **Think about the broader impact** - how would this affect other users?
-        - 📋 **Consider implementation complexity** - is this a small change or a major feature?
-        - ✂️ **Keep it short.** Describe the problem you're trying to solve and why existing behavior falls short. Skip proposed implementations unless you have a specific, well-considered suggestion — we don't need LLM-generated API designs. Requests that are difficult to parse may be closed without response.
+        ### Before you submit
 
-        Thanks for helping to make FastMCP better! 🚀
+        - 🔍 **Check if this has already been requested** — search existing issues first
+        - 🎯 **Describe the problem you're trying to solve**, not the solution you want — we'll figure out the best implementation
+        - ✂️ **Keep it short.** A motivating description and a concrete use case is the ideal request — aim to fit in a single screen. Skip proposed implementations, API designs, or multi-option analyses — maintainers will figure out the approach. Requests that are difficult to parse will be labeled `too-long` and not triaged until condensed.
+        - 🤖 **Using an LLM?** Great — but it must follow these guidelines. Generic LLM output that ignores our contributing conventions will be closed. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
   - type: textarea
     id: description
     attributes:
       label: Enhancement
       description: |
-        Please describe the enhancement:
+        What problem or use case does this solve? How does current behavior fall short?
 
-        - What problem or use case would it solve?
-        - How would it improve your workflow or experience with FastMCP?
-        - Are there any alternative solutions you've considered?
+        Focus on the *what* and *why* — the motivating scenario. You don't need to propose an API or implementation.
     validations:
       required: true

.github/actions/run-pytest/action.yml

@@ -3,7 +3,7 @@ description: "Run pytest with appropriate flags for the test type and platform"
 
 inputs:
   test-type:
-    description: "Type of tests to run: unit, integration, or client_process"
+    description: "Type of tests to run: unit, integration, client_process, or conformance"
     required: false
     default: "unit"
 
@@ -23,8 +23,13 @@ runs:
           TIMEOUT="5"
           MAX_PROCS="0"
           EXTRA_FLAGS="-x"
+        elif [ "${{ inputs.test-type }}" == "conformance" ]; then
+          MARKER="conformance"
+          TIMEOUT="120"
+          MAX_PROCS="0"
+          EXTRA_FLAGS="-x"
         else
-          MARKER="not integration and not client_process"
+          MARKER="not integration and not client_process and not conformance"
           TIMEOUT="5"
           MAX_PROCS="4"
           EXTRA_FLAGS=""
@@ -38,6 +43,7 @@ runs:
         uv run --no-sync pytest \
           --inline-snapshot=disable \
           --timeout=$TIMEOUT \
+          --durations=50 \
           -m "$MARKER" \
           $PARALLEL_FLAGS \
           $EXTRA_FLAGS \

.github/pull_request_template.md

@@ -1,28 +1,22 @@
 ## Description
-<!-- 
-Please provide a clear and concise description of the changes made in this pull request.
 
-Using AI to generate code? Please include a note in the description with which AI tool you used.
--->
+<!-- What does this PR do? Link to the issue it addresses. -->
 
-**Contributors Checklist**
-<!--
-NOTE:
-1. You must create an issue in the repository before making a Pull Request.
-2. You must not create a Pull Request for an issue that is already assigned to someone else.
+Closes #
 
-If you do not follow these steps, your Pull Request will be closed without review.
--->
+## Contribution type
 
-- [ ] My change closes #(issue number)
-- [ ] I have followed the repository's development workflow
-- [ ] I have tested my changes manually and by adding relevant tests
-- [ ] I have performed all required documentation updates
+<!-- Check the one that applies. If you're unsure whether your change is welcome, please open an issue first — see CONTRIBUTING.md. -->
 
-**Review Checklist**
-<!-- Your Pull Request will not be reviewed if tests are failing, you have not self-reviewed your changes, or you have not checked all of the following: -->
+- [ ] Bug fix (simple, well-scoped fix for a clearly broken behavior)
+- [ ] Documentation improvement
+- [ ] Enhancement (maintainers typically implement enhancements — see [CONTRIBUTING.md](../CONTRIBUTING.md))
 
-- [ ] I have self-reviewed my changes
-- [ ] My Pull Request is ready for review
+## Checklist
 
----
+- [ ] This PR addresses an existing issue (or fixes a self-evident bug)
+- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] I have added tests that cover my changes
+- [ ] I have run `uv run prek run --all-files` and all checks pass
+- [ ] I have self-reviewed my changes
+- [ ] If I used an LLM, it followed the repo's contributing conventions (not generic output)

.github/release.yml

@@ -8,26 +8,33 @@ changelog:
       labels:
         - feature
 
-    - title: Enhancements 🔧
+    - title: Breaking Changes ⚠️
       labels:
-        - enhancement
+        - breaking change
       exclude:
         labels:
-          - breaking change
+          - contrib
+          - security
 
-    - title: Fixes 🐞
+    - title: Enhancements ✨
       labels:
-        - bug
+        - enhancement
       exclude:
         labels:
-          - contrib
+          - breaking change
+          - security
 
-    - title: Breaking Changes 🛫
+    - title: Security 🔒
       labels:
-        - breaking change
+        - security
+
+    - title: Fixes 🐞
+      labels:
+        - bug
       exclude:
         labels:
           - contrib
+          - security
 
     - title: Docs 📚
       labels:
@@ -41,6 +48,9 @@ changelog:
     - title: Dependencies 📦
       labels:
         - dependencies
+      exclude:
+        labels:
+          - security
 
     - title: Other Changes 🦾
       labels:

.github/workflows/auto-close-duplicates.yml

@@ -20,7 +20,7 @@ jobs:
 
       - name: Generate Marvin App token
         id: marvin-token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
         with:
           app-id: ${{ secrets.MARVIN_APP_ID }}
           private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}

.github/workflows/auto-close-needs-mre.yml

@@ -20,7 +20,7 @@ jobs:
 
       - name: Generate Marvin App token
         id: marvin-token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
         with:
           app-id: ${{ secrets.MARVIN_APP_ID }}
           private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}

.github/workflows/martian-test-failure.yml

@@ -29,7 +29,7 @@ jobs:
 
       - name: Generate Marvin App token
         id: marvin-token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
         with:
           app-id: ${{ secrets.MARVIN_APP_ID }}
           private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}

.github/workflows/martian-triage-issue.yml

@@ -33,7 +33,7 @@ jobs:
 
       - name: Generate Marvin App token
         id: marvin-token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
         with:
           app-id: ${{ secrets.MARVIN_APP_ID }}
           private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}

.github/workflows/marvin-comment-on-issue.yml

@@ -36,14 +36,9 @@ jobs:
       - name: Install dependencies
         run: uv sync --python 3.12
 
-      - name: Run prek
-        uses: j178/prek-action@v1
-        env:
-          SKIP: no-commit-to-branch
-
       - name: Generate Marvin App token
         id: marvin-token
-        uses: actions/create-github-app-token@v2
+        uses: actions/create-github-app-token@v3
         with:
           app-id: ${{ secrets.MARVIN_APP_ID }}
           private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}