Added RFC 6570 complaint form style query expansion as optional param…

[codecracker007]

Add RFC 6570 support for optional parameters as form-style query expansions

Motivation and Context

Adds optional parameter support with RFC 6570 compliance as form-style query expansions. This change addresses issue #378, .

Breaking Changes

None

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[ihrpr]

Thank you for working on this!

This PR makes good progress toward RFC 6570 support by adding form-style query expansion.

There are a few suggestions:

1. Type Conversion for Query Parameters. Query parameters from URLs are always strings, but the code doesn't convert them to match function parameter
   types.

Example of the problem:

@server.resource("resource://items/{category}{?limit}")
def get_items(category: str, limit: int = 10) -> str:
    # When called with resource://items/books?limit=20
    # limit will be string "20" not int 20
    return f"Items in {category}, limit: {limit} (type: {type(limit)})"

Suggested fix: Add type conversion based on function annotations in

2. Handle Edge Cases in Query Parsing. The current implementation might not handle edge cases properly:

• Empty query values (?param=)
• URL-encoded values (?name=John%20Doe)

3. Add Tests for Type Conversion Scenarios

4. Consider Documenting Query Parameter Behavior

[codecracker007]

@ihrpr thanks for the feedback

during the fn call with params result = self.fn(**params)

can i use call_fn_with_arg_validation

python-sdk/src/mcp/server/fastmcp/utilities/func_metadata.py

Line 45 in f2f4dbd

async def call_fn_with_arg_validation(

for type validation and conversion and should i fallback to default values for optional parameters if validation fails for any one of them

[codecracker007]

@ihrpr the pydantic validate_call already takes care of the compatible type conversion based on annontated parameters for query parameters and raises validation error for incompatible types added a decorator which check if the validation error is raised by optional parameters and ignores them so they fall back to default values to keep it compliant

added relevant tests covering these cases

for the cases in query parsing the empty values and url encoded parameters are handled by parse_qs added relevant tests covering these

[felixweinberger]

Apologies for the delay in coming back to this - there seem to be some failing tests & merge conflicts, would you be able to resolve?

I'll prioritize responding quickly if you have the bandwidth to update the PR here.

[felixweinberger]

Hi @codecracker007 thank you for this contribution.

I think this PR is heading in the right direction in terms of adding support for optional params on resources. However, to lower the maintenance burden as well as adhering to a "fail fast" principle, we shouldn't do the automatic retry logic when clients provide invalid optional params and fallback to the default.

If clients pass in invalid optional params, we should just fail like we would have without this retry logic.

[felixweinberger]

We should fail fast if an optional parameter was provided with a non-matching type.

I think we should completely remove this as well as the call to it in templates.py

[felixweinberger]

note: removing this validation makes sense because we now support optional params.

[felixweinberger]

remove, we should fail fast and not silently when invalid params are provided by clients.

[felixweinberger]

don't use a fallback, just fail if the optional params are supplied incorrectly

[felixweinberger]

thank you for adding significant test coverage - we'll want to update these to catch expected validation errors rather than the fallback logic.

[felixweinberger]

original_fn, fn, final_fn - this gets quite confusing.

I think if we remove the use_defaults_on_optional_validation_error we shouldn't need any of these and can just stick to fn

[Kludex]

Don't we want something more FastAPI-ish? Like Annotated[type[T], Query()]? 🤔

[felixweinberger]

Don't we want something more FastAPI-ish? Like Annotated[type[T], Query()]? 🤔

Something like this?

from typing import Annotated

@mcp.resource("search://{category}/{id}")
def search(
    category: Annotated[str, Path()],
    id: Annotated[int, Path()],
    format: Annotated[str, Query()] = "json",
    limit: Annotated[int, Query()] = 10
):
    ...

Note: there's also #1439 which is touching the same area so we'd need some coordination cc: @beaterblank

[Kludex]

Don't we want something more FastAPI-ish? Like Annotated[type[T], Query()]? 🤔

Something like this?

from typing import Annotated

@mcp.resource("search://{category}/{id}")
def search(
    category: Annotated[str, Path()],
    id: Annotated[int, Path()],
    format: Annotated[str, Query()] = "json",
    limit: Annotated[int, Query()] = 10
):
    ...

Note: there's also #1439 which is touching the same area so we'd need some coordination cc: @beaterblank

For category and id, you wouldn't need it, but you could... Also, I think Query/Path would have the default parameter, so you don't need to add default in the parameters.

[felixweinberger]

Don't we want something more FastAPI-ish? Like Annotated[type[T], Query()]? 🤔

Something like this?

from typing import Annotated

@mcp.resource("search://{category}/{id}")
def search(
    category: Annotated[str, Path()],
    id: Annotated[int, Path()],
    format: Annotated[str, Query()] = "json",
    limit: Annotated[int, Query()] = 10
):
    ...

Note: there's also #1439 which is touching the same area so we'd need some coordination cc: @beaterblank

For category and id, you wouldn't need it, but you could... Also, I think Query/Path would have the default parameter, so you don't need to add default in the parameters.

OK thanks, so more like this?

from typing import Annotated

@mcp.resource("search://{category}/{id}")
def search(
    category: str,
    id: int,
    format: Annotated[str, Query(default="json")],
    limit: Annotated[int, Query(default=10)],
):
    ...

[beaterblank]

Don't we want something more FastAPI-ish? Like Annotated[type[T], Query()]? 🤔

Something like this?

from typing import Annotated

@mcp.resource("search://{category}/{id}")
def search(
    category: Annotated[str, Path()],
    id: Annotated[int, Path()],
    format: Annotated[str, Query()] = "json",
    limit: Annotated[int, Query()] = 10
):
    ...

Note: there's also #1439, which is touching the same area, so we'd need some coordination cc: @beaterblank

Yes, using Annotated sounds like a good approach, but we should ideally support both styles.

Also, a small nitpick, the classes should be named PathParameter and QueryParameter, since I spent a few minutes confused :) or maybe its best stick with how fast api does it.

I also noticed an issue in my PR: I’m currently inferring types only from the URI, but this should be done based on the function signature value's types instead. can reuse the code from this PR for that.

Additionally, since both features modify the same function in different ways, we should refactor the logic into smaller, more focused functions. That will make the codebase cleaner and easier to extend in the future.

At this point, I could either merge this PR into mine and resolve the conflicts properly, or do it the other way around.

merging this into #1439

[beaterblank]

Can close this PR merged into #1439 .