feat: RFC 6570 URI templates with operator-aware security

docs/migration.md

@@ -545,6 +545,57 @@
 await client.read_resource(str(my_any_url))
 ```
 
+### Resource templates: matching behavior changes
+
+Resource template matching has been rewritten with RFC 6570 support.
+Four behaviors have changed:
+
+**Path-safety checks applied by default.** Extracted parameter values
+containing `..` as a path component or looking like an absolute path
+(`/etc/passwd`, `C:\Windows`) now cause the template to not match.
+This is checked on the decoded value, so `..%2Fetc` and `%2E%2E` are
+caught too. Note that `..` is only flagged as a standalone path
+component, so values like `v1.0..v2.0` or `HEAD~3..HEAD` are unaffected.
+
+If a parameter legitimately needs to receive absolute paths or
+traversal sequences, exempt it:
+
+```python
+from mcp.server.mcpserver import ResourceSecurity
+
+@mcp.resource(
+    "inspect://file/{+target}",
+    security=ResourceSecurity(exempt_params={"target"}),
+)
+def inspect_file(target: str) -> str: ...
+```
+
+**Template literals are regex-escaped.** Previously a `.` in your
+template matched any character; now it matches only a literal dot.
+`data://v1.0/{id}` no longer matches `data://v1X0/42`.
+
+**Query parameters match leniently.** A template like
+`search://{q}{?limit}` now matches `search://foo` (with `limit` absent
+from the extracted params so your function default applies). Previously
+this returned no match. If you relied on all query parameters being
+required, add explicit checks in your handler.
+
+**Malformed templates fail at decoration time.** Unclosed braces,
+duplicate variable names, and unsupported syntax now raise
+`InvalidUriTemplate` when the decorator runs, rather than silently
+misbehaving at match time.
+
+**Static URIs with Context-only handlers now error.** A non-template
+URI paired with a handler that takes only a `Context` parameter
+previously registered but was silently unreachable (the resource
+could never be read). This now raises `ValueError` at decoration time.
+Context injection for static resources is planned; until then, use a
+template with at least one variable or access context through other
+means.
+
+See [Resources](server/resources.md) for the full template syntax,
+security configuration, and filesystem safety utilities.
+
 ### Lowlevel `Server`: constructor parameters are now keyword-only
 
 All parameters after `name` are now keyword-only. If you were passing `version` or other parameters positionally, use keyword arguments instead: