Recommendation

Change middleware return type annotations from list[...] to Sequence[...] for all list-returning methods in the Middleware base class. This is a legitimate type safety issue that affects middleware subclasses and was already identified and fixed for a similar issue in PR #1882 (ctx.sample types). The fix is straightforward and aligns with established Python typing best practices.

Findings

The Covariance Problem

Lists in Python are invariant, meaning list[Tool] is not compatible with list[FastMCPComponent] even though Tool is a subclass of FastMCPComponent. This prevents middleware subclasses from properly typing their return values when they want to return a more specific type.

Current problematic signatures in src/fastmcp/server/middleware/middleware.py:

# Lines 178-204
async def on_list_tools(...) -> list[Tool]: ...
async def on_list_resources(...) -> list[Resource]: ...
async def on_list_resource_templates(...) -> list[ResourceTemplate]: ...
async def on_list_prompts(...) -> list[Prompt]: ...
async def on_read_resource(...) -> list[ReadResourceContents]: ...

Precedent in Codebase

Issue #1881 (closed by PR #1882) reported the exact same problem:

"the messages is list[str | SamplingMessage], it should be a Sequence so users dont get type errors if they pass a list[str] or a list[SamplingMessage]"

This was fixed by changing to Sequence types. The project already uses Sequence in several places:

src/fastmcp/utilities/components.py:19 - _convert_set_default_none accepts Sequence[T]
The codebase imports Sequence from collections.abc

Impact on Middleware Authors

When writing custom middleware, developers may want to return filtered or transformed lists. With the current list annotation, type checkers will complain about covariance violations. Using Sequence (which is covariant) solves this problem while maintaining full backwards compatibility since list implements Sequence.

Detailed Action Plan

Files to Modify

Primary file: src/fastmcp/server/middleware/middleware.py

Changes Required

Add import (if not present):
```
from collections.abc import Sequence
```

Update method signatures (lines 164-204):

Before:

async def on_read_resource(...) -> list[ReadResourceContents]:
async def on_list_tools(...) -> list[Tool]:
async def on_list_resources(...) -> list[Resource]:
async def on_list_resource_templates(...) -> list[ResourceTemplate]:
async def on_list_prompts(...) -> list[Prompt]:

After:

async def on_read_resource(...) -> Sequence[ReadResourceContents]:
async def on_list_tools(...) -> Sequence[Tool]:
async def on_list_resources(...) -> Sequence[Resource]:
async def on_list_resource_templates(...) -> Sequence[ResourceTemplate]:
async def on_list_prompts(...) -> Sequence[Prompt]:

Update CallNext type parameters in the same methods:

Before:

call_next: CallNext[mt.ReadResourceRequestParams, list[ReadResourceContents]]
call_next: CallNext[mt.ListToolsRequest, list[Tool]]
call_next: CallNext[mt.ListResourcesRequest, list[Resource]]
call_next: CallNext[mt.ListResourceTemplatesRequest, list[ResourceTemplate]]
call_next: CallNext[mt.ListPromptsRequest, list[Prompt]]

After:

call_next: CallNext[mt.ReadResourceRequestParams, Sequence[ReadResourceContents]]
call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]]
call_next: CallNext[mt.ListResourcesRequest, Sequence[Resource]]
call_next: CallNext[mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]]
call_next: CallNext[mt.ListPromptsRequest, Sequence[Prompt]]

Testing Strategy

Run type checker:
```
uv run ty check
```

Run existing middleware tests:

uv run pytest tests/server/middleware/ -v

Verify no runtime changes: Since list implements Sequence, all existing code remains fully functional. This is purely a type annotation improvement.
Test with custom middleware: Create a test case where a middleware subclass returns a filtered list to verify type checkers accept the covariant return type.

Pre-commit Checklist

uv sync                              # Install dependencies
uv run pre-commit run --all-files    # Ruff + Prettier + ty
uv run pytest                        # Run full test suite

Related Issues and Pull Requests

Repository	Issue or PR	Relevance
jlowin/fastmcp	#1881: Improper types for `ctx.sample`	Exact same covariance issue, fixed by using Sequence instead of list
jlowin/fastmcp	#1882: Small updates to Sampling types	The PR that fixed #1881 by changing to Sequence types - direct precedent
jlowin/fastmcp	#1851: Incorrect typing for read_resource middleware method	Related middleware typing issue (return type mismatch)

Related Files

Repository	File	Relevance	Sections
jlowin/fastmcp	middleware.py	Contains all affected method signatures	Lines 164-204 (all list-returning methods)
jlowin/fastmcp	components.py	Already uses Sequence for type flexibility	Line 19 (_convert_set_default_none)
jlowin/fastmcp	context.py	Fixed similar issue in PR #1882	sample() method signatures

Middleware should return Sequences not Lists #2055

Description

Description

Example Code

Version Information

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions