Fix decorator error messages to link to correct doc pages

[jlowin]

Error messages for @prompt and @resource decorators were incorrectly linking to the tools documentation page. Now each decorator type links to its own "Using with Methods" section:

• @tool errors → /servers/tools#using-with-methods
• @resource errors → /servers/resources#using-with-methods
• @prompt errors → /servers/prompts#using-with-methods

[coderabbitai]

Walkthrough

This pull request updates documentation reference URLs in error and help messages across two files. In the function prompt decorator, the error message URL is updated to point to the prompts section. In the local provider, three error/help message paths are modified to redirect users to more appropriate documentation anchors: the tool decorator now points to resources documentation, while two prompt-related code paths point to prompts documentation. These changes improve the accuracy of user-facing guidance without altering any functional behavior or control flow logic.

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The pull request description explains what was fixed but lacks the required checklist items from the template (Contributors Checklist and Review Checklist are empty).	Complete the Contributors Checklist and Review Checklist by filling in the relevant checkboxes and providing the issue number that this PR closes.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: fixing decorator error messages to link to correct documentation pages, which matches the changeset focus.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 07d89c4 and ba0f6cd.

📒 Files selected for processing (2)

• src/fastmcp/prompts/function_prompt.py
• src/fastmcp/server/providers/local_provider.py

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Python ≥3.10 with full type annotations required for all code
Never use bare except - be specific with exception types in Python code

Files:

• src/fastmcp/server/providers/local_provider.py
• src/fastmcp/prompts/function_prompt.py

🧠 Learnings (1)

📚 Learning: 2026-01-12T16:24:54.978Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2026-01-12T16:24:54.978Z
Learning: Applies to src/prompts/**/*.{ts,tsx,js,jsx} : Changes affecting MCP Prompts (like adding tags, importing, etc.) must be adopted, applied, and tested consistently

Applied to files:

• src/fastmcp/prompts/function_prompt.py

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Run tests: Python 3.13 on ubuntu-latest
• GitHub Check: Run tests: Python 3.10 on windows-latest
• GitHub Check: Run tests: Python 3.10 on ubuntu-latest
• GitHub Check: Run tests with lowest-direct dependencies

🔇 Additional comments (5)

src/fastmcp/prompts/function_prompt.py (1)

387-391: LGTM!

The URL correction properly directs users to the prompts documentation section when they encounter classmethod ordering issues with the @prompt decorator.

src/fastmcp/server/providers/local_provider.py (4)

718-731: LGTM!

The URL now correctly directs users to the resources documentation section for the @resource decorator's unbound method error.

---

869-873: LGTM!

The URL correction properly directs users to the prompts documentation section for the classmethod ordering error in the @prompt decorator.

---

883-896: LGTM!

The URL now correctly points to the prompts documentation section for the unbound method error in the @prompt decorator.

---

537-541: Note: AI summary contains an inaccuracy.

The AI-generated summary incorrectly states "Tool decorator now redirects to resources#using-with-methods". The tool decorator URL at line 540 and 563 remains unchanged and correctly points to tools#using-with-methods. Only the resource and prompt decorator URLs were modified in this PR.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[marvin-context-protocol]

Test Failure Analysis

Summary: The loq file size check is failing because docs/development/v3-notes/v3-features.mdx has grown to 539 lines, exceeding its configured limit of 536 lines.

Update (2026-01-13 03:22 UTC): This PR was merged to main, and the static analysis is now failing on the main branch (workflow run #20943454244). The loq limit needs to be updated to unblock CI.

Root Cause: This is a pre-existing issue, not caused by this PR. The file grew to 539 lines in commit 07d89c4 (PR #2836 - "Add transform system for modifying components in provider chains"). However, the loq limit wasn't updated at that time, and now the static analysis is catching the violation.

Suggested Solution: Update the loq limit for this file in loq.toml:

[[rules]]
path = "docs/development/v3-notes/v3-features.mdx"
max_lines = 539  # Update from 536 to 539

Run loq baseline to automatically update the limit:

uv run loq baseline

Detailed Analysis

Log excerpt showing the failure:

loq (file size limits)...................................................[41mFailed[49m
[2m- hook id: loq[0m
[2m- exit code: 1[0m

  ✖    539 > 536    docs/development/v3-notes/v3-features.mdx
  1 violation (17ms)

Why this is happening:

• This PR changes only error message links in src/fastmcp/prompts/function_prompt.py and src/fastmcp/server/providers/local_provider.py
• The v3-features.mdx file was not modified in this PR
• The file grew from 536 to 539 lines in a previous commit (07d89c4) but the loq limit wasn't updated then
• The static analysis runs on all files with --all-files, catching this pre-existing violation

Related Files

• loq.toml:310-311 - Contains the outdated limit (536) for this file
• docs/development/v3-notes/v3-features.mdx - The file that exceeds its limit (539 lines)
• .pre-commit-config.yaml - Configures the loq hook that runs during CI

[marvin-context-protocol]

Test Failure Analysis

Summary: The failing test is a flaky timing-based test unrelated to the PR changes. The test creates a JWT token with a 1-second expiration and expects it to be valid immediately, but the token expired between creation and verification.

Root Cause: This is a race condition in the test itself. The test at creates a token with expires_in=1 (1 second) and immediately tries to verify it on line 175. However, the token creation at 03:17:51 with exp=1768274271 (expires at timestamp 1768274271) had already expired by the time verification was attempted, indicating that the operations took slightly over 1 second to complete between token issuance and the first verification call.

Suggested Solution: Increase the initial token lifetime in the test to provide a larger timing buffer. Change line 171 from expires_in=1 to expires_in=5 or higher. This gives enough time for the immediate verification while still allowing the test to complete reasonably quickly (the sleep on line 179 would need to be updated to time.sleep(5.1)).

Detailed Analysis

From the CI logs:

DEBUG    Issued access token for           jwt_issuer.py:138
         client=client-abc jti=token-id                     
         exp=1768274271                                     
[01/13/26 03:17:51] DEBUG    Token expired                     jwt_issuer.py:216

The token was issued with expiration timestamp 1768274271 (now + 1 second), but by the time verify_token was called on what should be an immediate verification, the token had already expired.

The test logic:

1. Line 167-172: Creates token with 1-second expiration
2. Line 175: Immediately verifies token (expects success) - FAILED HERE
3. Line 179: Sleeps 1.1 seconds
4. Line 182-183: Verifies token (expects failure)

The JWT verification code at src/fastmcp/server/auth/jwt_issuer.py:215-217 checks:

if exp and exp < time.time():
    logger.debug("Token expired")
    raise JoseError("Token has expired")

This is a timing race condition where the test operations took slightly longer than expected.

Related Files

• tests/server/auth/test_jwt_issuer.py: Test file containing the flaky test (line 164-183)
• src/fastmcp/server/auth/jwt_issuer.py: JWT issuer implementation (lines 122-145 for token creation, 213-217 for expiration validation)

Note: This test failure is completely unrelated to the PR changes, which only update documentation links in decorator error messages.