Enhanced ResourceTemplate URI matching and type handling logic.

[beaterblank]

Feature Added:
Enhanced ResourceTemplate URI matching and type handling logic.

Motivation and Context

This change introduces a typed-aware URI parsing mechanism similar to FastAPI’s path parameter system.
It resolves issue #220 by adding a more flexible and self-contained approach for handling resource URIs with type annotations.

How Has This Been Tested?

• Verified functionality through new and existing unit tests for:

  • Typed placeholders ({name:str}, {id:int}, {value:float}, {uuid:UUID}, {path:path})
  • Automatic type conversion and validation

• Confirmed correct parameter extraction and type enforcement in all matching scenarios.

Breaking Changes

• None expected, but users relying on untyped string-only behaviour may observe typed conversions.

Types of changes

• New feature (non-breaking change which adds functionality)

Checklist

• I have read the [MCP Documentation](https://modelcontextprotocol.io)
• 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

Additional context

The implementation assumes URI templates follow a strict pattern and defaults to str when no type is provided.
Optional parameters and wildcard matching beyond {path: path} are not supported / cannot be supported.

[beaterblank]

Hello, @felixweinberger, would you be able to help find someone who could review the code? Thank you!

[maxisbey]

related: #436

[felixweinberger]

Hi @beaterblank thank you for this contribution - FYI there's another PR #427 that's also enhancing URI handling, though for a slightly different usecase, might be some conflicts.

This PR takes the convertor approach suggested in #220, but @Kludex raised a good point on #427 whether we should aim for more of a FastAPI-level design, which makes sense in terms of abstraction level to me.

Rather than embedding convertor syntax in the URI template ({path:path}, {id:int}), we could specify parameter behavior in the function signature using Annotated:

from typing import Annotated

@mcp.resource("files://{path}")
def get_file(path: Annotated[str, Path(allow_slashes=True)]):
    ...

This would also provide a unified way to handle both path and query parameters:

@mcp.resource("search://{category}")
def search(
    category: str,  # Simple path param, no annotation needed
    format: Annotated[str, Query(default="json")],  # Query param
    limit: Annotated[int, Query(default=10)]
):
    ...

[beaterblank]

Hi @beaterblank thank you for this contribution - FYI there's another PR #427 that's also enhancing URI handling, though for a slightly different usecase, might be some conflicts.

This PR takes the convertor approach suggested in #220, but @Kludex raised a good point on #427 whether we should aim for more of a FastAPI-level design, which makes sense in terms of abstraction level to me.

Rather than embedding convertor syntax in the URI template ({path:path}, {id:int}), we could specify parameter behavior in the function signature using Annotated:

from typing import Annotated

@mcp.resource("files://{path}")
def get_file(path: Annotated[str, Path(allow_slashes=True)]):
    ...

This would also provide a unified way to handle both path and query parameters:

@mcp.resource("search://{category}")
def search(
    category: str,  # Simple path param, no annotation needed
    format: Annotated[str, Query(default="json")],  # Query param
    limit: Annotated[int, Query(default=10)]
):
    ...

Yes, I've also just noticed this, and this is partly done in #427 ,

[beaterblank]

Should This be a ValueError? Since it only happens when the converter has a bad implementation of converting.

Should we go for RuntimeError?

[beaterblank]

Hi @beaterblank thank you for this contribution - FYI there's another PR #427 that's also enhancing URI handling, though for a slightly different usecase, might be some conflicts.
This PR takes the convertor approach suggested in #220, but @Kludex raised a good point on #427 whether we should aim for more of a FastAPI-level design, which makes sense in terms of abstraction level to me.
Rather than embedding convertor syntax in the URI template ({path:path}, {id:int}), we could specify parameter behavior in the function signature using Annotated:

from typing import Annotated

@mcp.resource("files://{path}")
def get_file(path: Annotated[str, Path(allow_slashes=True)]):
    ...

This would also provide a unified way to handle both path and query parameters:

@mcp.resource("search://{category}")
def search(
    category: str,  # Simple path param, no annotation needed
    format: Annotated[str, Query(default="json")],  # Query param
    limit: Annotated[int, Query(default=10)]
):
    ...

Yes, I've also just noticed this, and this is partly done in #427 ,

Merging #427 into this.

[beaterblank]

Merged #427

Currently working on the Annotated parameter logic implementation, and addressing comments from #427.
Reference: fastapi/param_functions.py

While reviewing the merge, I noticed this line in the MCP SDK:

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

Line 1073 in 40acbc5

class Context(BaseModel, Generic[ServerSessionT, LifespanContextT, RequestT]):

Should we leave this as-is and handle Path and Query separately, or try to integrate context injection here as well?
Integrating it could introduce regressions or break existing behaviour.

[beaterblank]

weather://{city}/current{?units,format})
Removing the query parameter hints from the UI. Instead, using function annotations to define parameters, skipping known parameters such as Context, and treating any remaining parameters automatically as query parameters.