kotlin-sdk-core/io.modelcontextprotocol.kotlin.sdk.utils/PathSegmentTemplateMatcher

PathSegmentTemplateMatcher

class PathSegmentTemplateMatcher @JvmOverloads constructor(val resourceTemplate: ResourceTemplate, maxDepth: Int = MAX_DEPTH, maxUriLength: Int = MAX_URL_LENGTH) : ResourceTemplateMatcher(source)

A ResourceTemplateMatcher that matches resource URIs against an RFC 6570 Level 1 URI template by splitting both the URI and the template on / and comparing each segment in order.

Supported template syntax

Only RFC 6570 Level 1 is supported: simple {variable} expressions where the entire path segment is a single variable. Operator expressions ({+var}, {#var}, {.var}, {/var}, etc.) and multi-variable expressions ({a,b}) are not recognized — segments containing them are treated as literals.

Matching rules

The URI and template must have the same number of /-delimited segments.
Literal segments must match exactly (after percent-decoding the URI segment).
{variable} segments capture the percent-decoded URI segment value.
Query strings and fragments (?, #) are not stripped — they become part of the captured variable value for the segment that contains them.

Specificity scoring

When multiple templates match the same URI, each matched literal segment contributes 2 points and each variable capture contributes 1 point. The highest-scoring match wins.

Safety limits

URIs longer than maxUriLength characters are rejected.
Templates and URIs with more than maxDepth segments are rejected.

Security contract for handler authors

Values in MatchResult.variables are attacker-controlled strings extracted from the incoming URI. They are percent-decoded (one pass only) before being returned. Handlers must treat them as untrusted input and validate or sanitize them before using them to construct file paths, database queries, downstream URLs, or any other security-sensitive operation.

In particular:

A decoded value may contain /, .., null bytes (\u0000), ?, or #.
%252F in the URI becomes %2F in the variable — exactly one decode pass is applied.

Platform limitations

Dot-segment normalization (resolving .. and . in the URI path) is performed on JVM and JS targets using the platform-native URI parser. On native and WASM targets no normalizer is available, so dot-segment traversal is not mitigated at this layer — handlers on those targets must normalize paths themselves.