[DRAFT] feat: #502 resource templates

[kpavlov]

Motivation and Context

Implements MCP resource templates per the MCP 2025-11-25
specification.

Closing #502. Requires #603

Clients can now:

• Discover parameterized resource patterns via resources/templates/list
• Read any URI that matches a registered RFC 6570 template via resources/read

Changes

kotlin-sdk-server

• Server.addResourceTemplate(template, handler) — registers a ResourceTemplate with a two-parameter handler (ReadResourceRequest, Map<String, String>) -> ReadResourceResult, where the map contains the extracted URI variables.
• Server.addResourceTemplate(uriTemplate, name, …, handler) — convenience overload.
• Server.removeResourceTemplate(uriTemplate) — removes a registered template.
• Server.resourceTemplates — snapshot of all registered templates.
• handleReadResource now applies a three-tier lookup:
  1. Exact URI match against static resources (highest priority)
  2. Most-specific matching template (highest MatchResult.score from the RFC 6570 matcher)
  3. McpException(RESOURCE_NOT_FOUND) if nothing matches
• handleListResourceTemplates now returns the actual registered templates instead of an empty list.
• Template change notifications piggyback on resources/list_changed when that capability is enabled.

kotlin-sdk-core

• RPCError.ErrorCode.RESOURCE_NOT_FOUND = -32002 — new SDK-defined error code for
  unknown resource URIs.

• McpException.errorMessage — exposes the raw protocol message (without the
  "MCP error $code:" prefix) so Protocol can reconstruct the exact wire RPCError.
• Protocol.onRequest — error handler now propagates McpException.code,
  errorMessage, and data to the wire instead of always emitting INTERNAL_ERROR.

Conformance / integration tests

• conformance-baseline.yml: removes resources-templates-read from expected failures.
• ConformanceResources.kt: replaces workaround static resource with a real
  addResourceTemplate registration.
• AbstractResourceIntegrationTest.testInvalidResourceUri: updated to expect
  RESOURCE_NOT_FOUND (-32002) instead of INTERNAL_ERROR (-32603).

Breaking changes

handleReadResource now throws McpException(RESOURCE_NOT_FOUND) for unrecognised URIs instead of IllegalArgumentException. Clients receive error code -32002 on the wire instead of -32603. Any integration test asserting INTERNAL_ERROR for a missing resource must be updated (one such test is updated in this PR).

How Has This Been Tested?

• unit/integration tests.
• Existing integration and conformance tests pass with resources-templates-read removed from the baseline.

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

Additional context

[codecov-commenter]

Codecov Report

❌ Patch coverage is 86.66667% with 38 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...textprotocol/kotlin/sdk/utils/UriTemplateParser.kt	87.00%	0 Missing and 13 partials ⚠️
...o/modelcontextprotocol/kotlin/sdk/server/Server.kt	70.73%	1 Missing and 11 partials ⚠️
...extprotocol/kotlin/sdk/utils/UriTemplateMatcher.kt	80.95%	0 Missing and 8 partials ⚠️
...modelcontextprotocol/kotlin/sdk/shared/Protocol.kt	25.00%	0 Missing and 3 partials ⚠️
...delcontextprotocol/kotlin/sdk/utils/UriTemplate.kt	97.84%	0 Missing and 2 partials ⚠️

📢 Thoughts on this report? Let us know!