feat: add paginated list decorators for prompts, resources, and tools

[maxisbey]

Summary

This PR adds pagination support for listing prompts, resources, and tools using cursor-based pagination as defined in the MCP spec.

The lowlevel Server decorators list_resources, list_prompts, and list_tools now handle two types of handlers:

• No pagination (original functionality)
  • A handler with the signature Callable[[], Awaitable[list[<resource, prompt, or tool>]]]
  • This matches the original way these decorators work and means the API is still backwards compatible.
• Pagination (new functionality)
  • A handler with the signature Callable[[List<___>Request], Awaitable[List<___>Result]]
  • The cursor for a paginated request will be in the corresponding List<___>Request object depending on the decorator which the handle can now optionally handle.
  • The response object is a List<___>Response which the handler can specify the cursor for the next page.
  • This allows future extensions to the Request or Response objects to still be supported.

How It Works

The decorators now automatically detect whether a callback accepts a cursor parameter:

# Non-paginated (existing code continues to work)
@server.list_resources()
async def list_resources() -> list[Resource]:
    return [...]

# Paginated (new capability)
@server.list_resources()
async def list_resources(cursor: Cursor | None) -> ListResourcesResult:
    return ListResourcesResult(resources=[...], nextCursor="...")

Changes

• Modify list_prompts(), list_resources(), and list_tools() decorators to support both signatures
• Add comprehensive unit tests for pagination and signature detection
• Add examples demonstrating pagination usage
• Tool cache properly maintained for both paginated and non-paginated modes

Test plan

• Unit tests pass for all three decorators with both signatures
• Tests verify cursor passthrough for both None and string values
• Function inspection tests cover various callback signatures
• Backward compatibility verified with existing non-paginated handlers
• Manually tested via the inspector and with example client code

🤖 Generated with Claude Code

👨 Below generated by the human, Max Isbey

Manual testing

I spun up the MCP inspector and ran the example pagination server in both stdio mode and SSE mode. Below is some testing evidence using the SSE mode:

Clicking "List More Resources" correctly lists all 30 resources:

Note: this works for prompts and tools as well

Requesting a resource works:

Running the pagination client example code works listing all 30 resources:

[jerome3o-anthropic]

Can we have a some docs with examples? not sure if we have good docs for the lowlevel api but some usage examples would be great (if not just to help with reviewing).

Otherwise this looks good to me. happy with the separate functions to avoid breaking changes. keen to know how you think we should approach this in the high level interface.

[maxisbey]

Can we have a some docs with examples? not sure if we have good docs for the lowlevel api but some usage examples would be great (if not just to help with reviewing).

Otherwise this looks good to me. happy with the separate functions to avoid breaking changes. keen to know how you think we should approach this in the high level interface.

Updated the docs, added example code, and included testing in the PR desription

[Kludex]

Backward compatibility: Modifying the existing decorators to require a cursor parameter in the callback would break existing uses of these decorators.

You can make it optional, can't you?

[ochafik]

Exciting changes! Just some concerns about the accepts_request logic

[ochafik]

I think maybe the function we want is def accepts_single_positional_arg(func, arg_type)? (or can_be_called_with_single_positional to allow defaults)

[maxisbey]

I've renamed the function, but didn't include an arg_type because it's likely users will pass in an untyped handler which would then cause validation errors if we're checking for type hints.

[ochafik]

I think a handler w/ an untyped single pos param (or untyped *args) is perfectly fine, but if that single pos param does have a type it's a low hanging fruit to check it.

[jerome3o-anthropic]

w.r.t. the disagreement on runtime type checking the positional arg i'm personally okay with either approach, I think being maximally permissive (as long as the thing is technically correct) is a good devx. happy to be wrong, but keen to see this merged

[ochafik]

Thanks Max!

[ochafik]

Can you inline & simplify this function's / file logic? It is now calling inspect.signature up to twice (from 3 places). Something like this maybe?

def function_accepts_single_param(func: Callable[..., Any], param_type: type) -> bool:
    sig = inspect.signature(func)
    if not sig.parameters:
        # TODO: warn about old style without params
        return False
    elif len(sig.parameters) != 1:
        raise ValueError(f"Function must have exactly one parameter of type {type} or none (legacy).")

    param = next(iter(sig.parameters.values()))
    if param.kind not in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
        # TODO: warn about exotic param type
        return False
    
    if param.annotation == inspect.Parameter.empty or param.annotation == Any:
        # TODO: warn about untyped, depending on decision
        return False # or True if allow untyped

    return param.annotation == param_type

(not sure about swallowing the signature exceptions, removed it / better to fail loudly unless you know of legit cases that would throw?)

[maxisbey]

this code has been removed now

[ochafik]

I think we really only need to handle this case / can be prescriptive re/ signature of functions we allow (we don't need to allow all of valid python).

[ochafik]

can you also test def bad_pos_arg_type(request: str) and def good_untyped_pos_arg(request) ?

[ochafik]

@Kludex what's your take on allowing untyped def foo(request)?

[Kludex]

#1286 (comment)

I don't think any Python package should implement logic around positional arguments - modern packages rely on proper typing.

[maxisbey]

Hmm fair enough.

Alright so just so we can all be on the same page:

1. def foo(), def foo(thing: int = 1)
   • no exception, pass no request object, warn as deprecated
2. def foo(req: ListPromptsRequest), def foo(req: ListPromptsRequest, thing: int = 1)
   • no exception, will pass through the request
3. def foo(thing: int = 1, req: ListPromptsRequest | None = None)
   • no exception, pass no request object, warn as deprecated?
4. def foo(req), def foo(req: Any), def foo(req: Generic[T]), def foo(req: str)
   • no exception on registration, pass no request object, warn as deprected (even though it will fail at runtime)
5. def foo(thing: int, req: ListPromptsRequest)
   • do not raise exception, attempt to pass request at runtime (even though it will fail at runtime)

Note: No raising custom exception at registration time

Not sure if I'm missing anything else

[maxisbey]

Would be keen to hear your thought before I implement @Kludex and @ochafik

[maxisbey]

Had a call with @Kludex, we've agreed on the above (now updated) 5 examples for me to now implement and then get a re-review.

[maxisbey]

I've update the code to match the following except for adding the deprecation warnings.

I initially implemented it with deprecation (as you can see from the commented out code), but this infected the rest of the code base pretty thoroughly and caused a lot of issues with failed unit tests (from deprecation warnings), and the requirement of adding a lot of boilerplate code that generally isn't needed.

e.g. if you had:

@server.list_tools()
def handle_list_tools() -> list[Tool]:
    return [ <my one tool> ]

Then to avoid the deprecation warning you'd need to change it to:

@server.list_tools()
def handle_list_tools(_: ListToolsRequest) -> ListToolsResult:
    return ListToolsResult(tools=[ <my one tool> ])

I feel this is too much of a "breaking" change and would prefer to move the implementation/discussion around it into a separate PR rather than this one so we can get pagination in now.

[ochafik]

Thanks Max!

[ochafik]

won't this try and call def foo(x: str, req: param_name) as foo(req)? Also if you wanna handle defaults def foo(x=10, *, req: param_name) should work, and so should def foo(req: param_name, x=10)

[ochafik]

I think the key is to always inject by name (i.e. you won't have req in a positional-only situation, as def foo(x=1, req: param_name) is invalid w/o default for req).

Claude suggested something like this instead:

import inspect
import warnings
from collections.abc import Callable
from typing import Any, get_type_hints


def issue_deprecation_warning(func: Callable[..., Any], request_type: type) -> None:
    """
    Issue a deprecation warning for handlers that don't use the new request parameter style.
    """
    func_name = getattr(func, "__name__", str(func))
    warnings.warn(
        f"Handler '{func_name}' should accept a '{request_type.__name__}' parameter. "
        "Support for handlers without this parameter will be removed in a future version.",
        DeprecationWarning,
        stacklevel=4,
    )


def create_call_wrapper(func: Callable[..., Any], request_type: type) -> tuple[Callable[[Any], Any], bool]:
    """
    Create a wrapper function that knows how to call func with the request object.

    Returns a tuple of (wrapper_func, should_deprecate):
    - wrapper_func: A function that takes the request and calls func appropriately
    - should_deprecate: True if a deprecation warning should be issued

    Supports patterns like:
    - def handler(req: RequestType)  # inject req
    - def handler(*, req: RequestType)  # inject req
    - def handler(req: RequestType, x=10)  # inject req, x has default
    - def handler(x=10, *, req: RequestType)  # inject req, x has default
    - def handler()  # deprecated, no injection
    """
    try:
        sig = inspect.signature(func)
        type_hints = get_type_hints(func)
    except (ValueError, TypeError, NameError):
        # Can't inspect signature or resolve type hints, assume no request parameter (deprecated)
        return lambda _: func(), True

    # Find the request parameter
    request_param_name = None
    for param_name, param in sig.parameters.items():
        param_type = type_hints.get(param_name)
        if param_type == request_type:
            # Found a parameter with the request type
            if param.default is inspect.Parameter.empty:
                # It's required - this is our injection target
                request_param_name = param_name
                break
            # Has a default - treat as deprecated old style
            return lambda _: func(), True

    if request_param_name is None:
        # No request parameter found - deprecated
        return lambda _: func(), True

    # Validate all other parameters have defaults
    for param_name, param in sig.parameters.items():
        if param_name != request_param_name:
            if param.default is inspect.Parameter.empty and param.kind not in (
                inspect.Parameter.VAR_POSITIONAL,
                inspect.Parameter.VAR_KEYWORD,
            ):
                raise TypeError(
                    f"Handler '{getattr(func, '__name__', str(func))}' has required parameter '{param_name}' "
                    f"but only '{request_param_name}' should be required"
                )

    # Create wrapper that injects only the request parameter
    def wrapper(req: Any) -> Any:
        return func(**{request_param_name: req})

    return wrapper, False

[maxisbey]

This will intentionally fail later if you pass in func(thing: int, req: ListPromptsRequest). After some discussion with @Kludex this was the most "pythonic" common pattern.

Essentially, we're not going to raise any exceptions on registration, only at run-time. If you pass in a function with the wrong number of arguments, then that's on you. The type hinting is very explicit to saying your handler must have the correct type.

[maxisbey]

See this comment for the list of functionality/rules #1286 (comment)

[maxisbey]

(i.e. you won't have req in a positional-only situation, as def foo(x=1, req: param_name) is invalid w/o default for req).

You can have foo(req: ListPromptsRequest, /) which is positional only, no keywords. So foo(req=request) will fail.

[ochafik]

Cool, thanks for your patience, Max! Could you update the PR to mention the return type semantic change for annotated handlers? (we might wanna generalize this to all the other handlers as a follow up for consistency)

[maxisbey]

Cool, thanks for your patience, Max! Could you update the PR to mention the return type semantic change for annotated handlers? (we might wanna generalize this to all the other handlers as a follow up for consistency)

Updated!

Dismissing to unblock merging - all comments addressed as far as I can tell.